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COMPUTER EQUIPMENT AND SOFTWARE PURCHASED FROM A 
RADIO SHACK COMPANY-OWNED COMPUTER CENTER, RETAIL 
STORE OR FROM A RADIO SHACK FRANCHISEE OR DEALER AT ITS 
AUTHORIZED LOCATION 


LIMITED WARRANTY 


CUSTOMER OBLIGATIONS 


A. 


CUSTOMER. assumes full responsibility that this Radio Shack computer hardware purchased (the 
Equipment’), and any copies of Radio Shack software included with the Equipment or licensed 
separately (the ‘‘Software’’) meets the specifications, capacity, capabilities, versatility, and other 
requirements of CUSTOMER. 

CUSTOMER assumes full responsibility for the condition and effectiveness of the operating 
environment in which the Equipment and Software are to function, and for its installation. 


RADIO SHACK LIMITED WARRANTIES AND CONDITIONS OF SALE 


A. 


For a period of ninety (90) calendar days from the date of the Radio Shack sales document 
received upon purchase of the Equipment, RADIO SHACK warrants to the original CUSTOMER that 
the Equipment and the medium upon which the Software is stored is free from manufacturing 
defects. THIS WARRANTY IS ONLY APPLICABLE TO PURCHASES OF RADIO SHACK EQUIPMENT 
BY THE ORIGINAL CUSTOMER FROM RADIO SHACK COMPANY-OWNED COMPUTER CENTERS, 
RETAIL STORES AND FROM RADIO SHACK FRANCHISEES AND DEALERS AT ITS AUTHORIZED 
LOCATION. The warranty is void if the Equipment’s case or cabinet has been opened, or if the 
Equipment or Software has been subjected to improper or abnormal use. If a manufacturing defect 
is discovered during the stated warranty period, the defective Equipment must be returned to a 
Radio Shack Computer Center, a Radio Shack retail store, participating Radio Shack franchisee or 
Radio Shack dealer for repair, along with a copy of the sales document or lease agreement. The 
Original CUSTOMER’S sole and exclusive remedy in the event of a defect is limited to the 
Correction of the defect by repair, replacement, or refund of the purchase price, at RADIO 
SHACK’S election and sole expense. RADIO SHACK has no obligation to replace or repair 
expendable items. 

RADIO SHACK makes no warranty as to the design, capability, capacity, or suitability for use of 
the Software, except as provided in this paragraph. Software is licensed on an “‘AS IS”’ basis, 
without warranty. The original CUSTOMER’S exclusive remedy, in the event of a Software 
manufacturing defect, is its repair or replacement within thirty (30) calendar days of the date of the 
Radio Shack sales document received upon license of the Software. The defective Software shall 
be returned to a Radio Shack Computer Center, a Radio Shack retail store, participating Radio 
Shack franchisee or Radio Shack dealer along with the sales document. 

Except as provided herein no employee, agent, franchisee, dealer or other person is authorized to 
give any warranties of any nature on behalf of RADIO SHACK. 

Except as provided herein, RADIO SHACK MAKES NO WARRANTIES, INCLUDING WARRANTIES 
OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 

Some states do not allow limitations on how long an implied warranty lasts, so the above 
limitation(s) may not apply to CUSTOMER. 


LIMITATION OF LIABILITY 


A. 


EXCEPT AS PROVIDED HEREIN, RADIO SHACK SHALL HAVE NO LIABILITY OR RESPONSIBILITY 
TO CUSTOMER OR ANY OTHER PERSON OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS 
OR DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY 
“EQUIPMENT” OR “‘SOFTWARE’’ SOLD, LEASED, LICENSED OR FURNISHED BY RADIO SHACK, 
INCLUDING, BUT NOT LIMITED TO, ANY INTERRUPTION OF SERVICE, LOSS OF BUSINESS OR 
ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OR 
OPERATION OF THE ‘‘EQUIPMENT”’ OR ‘‘SOFTWARE”’. IN NO EVENT SHALL RADIO SHACK BE 
LIABLE FOR LOSS OF PROFITS, OR ANY INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES 
ARISING OUT OF ANY BREACH OF THIS WARRANTY OR IN ANY MANNER ARISING OUT OF OR 
CONNECTED WITH THE SALE, LEASE, LICENSE, USE OR ANTICIPATED USE OF THE ‘‘EQUIPMENT””’ 


OR “SOFTWARE”. 
continued 


NOTWITHSTANDING THE ABOVE LIMITATIONS AND WARRANTIES, RADIO SHACK’S LIABILITY 
HEREUNDER FOR DAMAGES INCURRED BY CUSTOMER OR OTHERS SHALL NOT EXCEED THE 
AMOUNT PAID BY CUSTOMER FOR THE PARTICULAR ‘‘EQUIPMENT’’ OR ‘‘SOFTWARE”’ 
INVOLVED. 

RADIO SHACK shall not be liable for any damages caused by delay in delivering or furnishing 
Equipment and/or Software. 

No action arising out of any claimed breach of this Warranty or transactions under this Warranty 
may be brought more than two (2) years after the cause of action has accrued or more than four 
(4) years after the date of the Radio Shack sales document for the Equipment or Software, 
whichever first occurs. 

Some states do not allow the limitation or exclusion of incidental or consequential damages, so the 
above limitation(s) or exclusion(s) may not apply to CUSTOMER. 


RADIO SHACK SOFTWARE LICENSE 


RADIO SHACK grants to CUSTOMER a non-exclusive, paid-up license to use the RADIO SHACK Software 
on one computer, subject to the following provisions: 


G. 


Except as otherwise provided in this Software License, applicable copyright laws shall apply to the 
Software. 

Title to the medium on which the Software is recorded (cassette and/or diskette) or stored (ROM) 
is transferred to CUSTOMER, but not title to the Software. 

CUSTOMER may use Software on one host computer and access that Software through one or 
more terminals if the Software permits this function. 

CUSTOMER shall not use, make, manufacture, or reproduce copies of Software except for use on 
one computer and as is specifically provided in this Software License. Customer is expressly 
prohibited from disassembling the Software. 

CUSTOMER is permitted to make additional copies of the Software only for backup or archival 
purposes or if additional copies are required in the operation of one computer with the Software, 
but only to the extent the Software allows a backup copy to be made. However, for TRSDOS 
Software, CUSTOMER is permitted to make a limited number of additional copies for 
CUSTOMER’S own use. 

CUSTOMER may resell or distribute unmodified copies of the Software provided CUSTOMER has 
purchased one copy of the Software for each one sold or distributed. The provisions of this 
Software License shall also be applicable to third parties receiving copies of the Software from 
CUSTOMER. 

All copyright notices shall be retained on all copies of the Software. 


APPLICABILITY OF WARRANTY 


A. 


The terms and conditions of this Warranty are applicable as between RADIO SHACK and 
CUSTOMER to either a sale of the Equipment and/or Software License to CUSTOMER or to a 
transaction whereby RADIO SHACK sells or conveys such Equipment to a third party for lease to 
CUSTOMER. 

The limitations of liability and Warranty provisions herein shall inure to the benefit of RADIO 
SHACK, the author, owner &nd/or licensor of the Software and any manufacturer of the Equipment 
sold by RADIO SHACK. 


STATE LAW RIGHTS 


The warranties granted herein give the original CUSTOMER specific legal rights, and the original 
CUSTOMER may have other rights which vary from state to state. 


spec tiatte! WERE 


D segs 


Ue ESSESSS 


@@eeeaeeeeoeoeoeoeoeeoeeoaeeoeoeoeeeeoeoeoeeoeeeeee @ 6 


TwyYyYyrerrryerurrereeeeUeeeeUUUUUUyUUuUeyy 


OS-9 Program Development 


OS-9 Program Development is in three parts: 


i. Text Editor 
Il. Assembler 
Il. Interactive Debugger 


You use these tools in developing an OS-9 program. The Text 
Editor lets you create a source program file. The Assembler lets 
you translate the source file to a machine-language file. With the 
Interactive Debugger you run and test the source program. 


OS-9 Operating System: © 1983 Microware Systems 
Corporation and Motorola Incorporated. 
All Rights Reserved. 
Licensed to Tandy Corporation. 


OS-9 Program Development: 
©1983 Tandy Corporation 
and Microware Systems Corporation. 
All Rights Reserved. 


UNIX is a trademark of Bell Laboratories. 
TRS-80 is a registered trademark of Tandy Corporation. 


Reproduction or use, without express written permission from 
Tandy Corporation or Microware Systems Corporation of any 
portion of this manual is prohibited. While reasonable efforts have 
been taken in the preparation of this manual to assure its accuracy, 
Tandy Corporation and Microware Systems Corporation assumes no 
liability resulting from any errors or omissions in this manual, or 
from the use of the information contained herein. 
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1 / Introduction 


Overview 


Text Buffers 


The OS-9 Macro Text Editor is a powerful but simply learned 
text-preparation system. It is commonly used to prepare text for 
letters and documents or text to be used by other OS-9 programs 
such as the assembler and high-level languages. The following 
features of the editor facilitate and expedite the text-preparation 
task. 


Compact size 

Multiple read and write files open simultaneously 
All OS-9 commands usable inside the text editor 
Adjustable workspace size 

Repeatable command sequences 

Edit macros 

Multiple text buffers 

Powerful commands 


The Macro Text Editor is an OS-9 executable module in posi- 
tion-independent, reentrant 6809 machine language. It is about 
5K bytes long and requires at least 2K bytes of free RAM to run. 
You may use the editor on any OS-9 system that has disk 
storage. 


As you enter text, the editor places it ina temporary storage area 
called a text buffer. Text buffers may be thought of as scratch 
pads used for saving text that you wish to manipulate with 
various edit commands. The Macro Text Editor can use multiple 
text buffers, one at a time. 


Edit Pointers 


The buffer in use is- the ‘‘primary buffer,’’ and the previous 
primary buffer is the ‘‘secondary buffer.’’ This manual refers to 
the primary buffer as the “‘edit buffer’’ or ‘‘buffer’’ for short. 
The secondary buffer is important only when you wish to use a 
command that moves text from one buffer to another. 


In the Macro Text Editor an edit pointer identifies your position 
in the buffer. This is similar to holding your place with your 
finger when reading a newspaper. 


Although the screen never shows the edit pointer, commands 
reposition it and display the text to which it points. Each buffer 
has its own edit pointer, which allows you to move from buffer 
to buffer without losing your place in any of them. 


Entering Commands 


The Macro Text Editor is an interactive editing system. You and 
the editor carry on a two-way conversation that goes through a 


cycle similar to the one below and continues until you type (Q). 


to quit editing. 


1. | EDIT shows E: on the screen, asking you to enter a 
command. ° 

2 You enter (type) a line with one or more commands 
on it. 

a, EDIT carries out the commands. 


4. EDIT shows E: on the screen, asking you to enter a 
command. 


When the screen shows E:, type one or more commands on a 
line and then type (always type to end a line). 
Enter each command by typing its name and any parameters 
(values) it needs. 
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If you enter more than one command on a line, separate the 
commands with a space. If a space is the first character on a line, 
however, the editor considers the space an insert an command 
and not a separator. 


Correct a typing error by backspacing or by deleting the entire 
line. You cannot correct a line after typing (ENTER). 


A description of all control characters is in the OS-9 Commands. 
Listed below are some of them. 


CLEAR)(A ) 

repeats the previous input line. 

CLEAR)(C ) 

interrupts the editor and returns to command entry mode. 
CLEAR)(D ) 

displays the current input on the next line. 

(CLEAR)CH) or 

backspaces, erases the previous character. 

(Q) 

interrupts the editor and returns to command entry mode. 
(CLEAR)(W) 


temporarily halts the data output to your terminal so that you can 
read the screen before the data scrolls off. Output resumes when 
you press any other key. 


CLEAR)(X ), (SHIFT), OR 
deletes the line. 
CLEAR)(BREAK 


interrupts the editor and returns to command entry mode. 


Command Parameters 


With many commands you specify a value that represents a 
parameter, for example, the number of times to repeat a com- 
mand or a phrase you wish to find. The two types of edit 
parameters are ‘‘numeric’’ and “‘string.’’ 


_ Numeric Parameters 


String Parameters 


Numeric parameters specify an amount, such as the number of 
times to repeat a command or the number of lines that a com- 
mand is to affect. If you do not specify a numeric parameter, the 
editor assumes you intend the default value of one. Specify all 
other numeric parameters in one of the following ways. 


hs 


Enter a positive decimal integer from 0 to 65,535. 
Examples: 

0 

10 

5250 

65532 

31 


Enter an asterisk (*) as a shorthand for 65,535. This 
is the editor’s notation for infinity. The asterisk is 
used to specify all remaining lines, all characters, or 
repeat forever. 


Use a numeric variable. (See Edit Macros, p. 000.) 


String parameters specify a single character, group of charac- 
ters, word, or phrase. Specify string parameters in either of the 
following ways. 


I. 


Enclose the group of characters with delimiters — 
two matching characters. You may use any charac- 
ters, but they must match. If one string immediately 
follows another, separate the two with a single 
delimiter that matches the others. Examples: 
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‘string of characters’’ 
/STRING/ 

: my name is Larry : 

‘‘first string’’second string’’ 
/string 1/ string 2/ 


Li Use a string variable. (See Edit Macros, p. 00/) 


Syntax Notation 


Syntax descriptions indicate what to enter and the order in which 
to do it. The command name is first; type this exactly as given. 
Following the command name are the parameters the command 
expects; enter each as it is described in the section on 


parameters. 


The syntax descriptions for each command use the following 


notations: 
n 
Str 
SPACEBAR 
text 


= numeric parameter 

string parameter 

space character 

= one or more characters terminated by 


typing (ENTER 


Below are examples of command syntaxes, how the command 
is used, and parameter requirements. 


Syntax 


CA) 
Vn 
Ln 
Snstr 


Cnstrstr 


Usage Parameter Requirements 
CLEAR None 
V5 1 numeric 
L 1 numeric 
S‘‘my string’’ 1 numeric and | 
S4/hello/ string 
S*/search string/ 
C*‘this’’that’’ 1 numeric and 2 
C3:this string: strings 

that string: 
C4/string// 
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Getting Started 


Start OS-9. When the screen shows OS-9, you are ready to enter 
the editor. To do so, type: 


EDIT (ENTER 


When the screen shows E:, enter a command. The first com- 
mand to learn is how to quit (exit) the editor. Type (Q) followed 
by (ENTER). 


The Q command terminates the editor and returns you to the 
OS-9 Shell, which responds with the OS-9: prompt. Learn a 
little about the other commands. Skim the first three sections on 
commands (**Displaying Text,’’ ‘‘Manipulating the Edit Point- 
er,’ ‘‘Inserting and Deleting Lines’’). 


Now enter the editor again and work through Sample Session 1. 
After you have mastered the first three sections of commands, 
move on to the more advanced commands and the other Sample 
Sessions. 


If you work with text files, enter the editor with an initial input 
and/or output file. Although you may open additional files after 
entering the editor, several commands treat the initial files as 
special cases (it is assumed that these files are the main working 
files); therefore, it may be advisable to specify your working 
files when you start the editor. 


Below is a list of ways in which the editor may be started, 
including the effect of each. A file that already exists is referred 
to as oldfile. A file to be created is referred to as newfile. 


EDIT OS-9 loads the editor and starts it. 
There is no initial read or write file. 
Perform text file operations by opening 
files after the editor is started. 


EDIT newfile OS-9 loads the editor and starts it. The 
editor creates a file called newfile, the 
initial write file. There is no initial read 
file; however, files may be read if they 
are opened after the editor is started. 


©@@eeeoeeeoeeeeeeeeeeeeeeeeeeeeeeeeeeede € 


TYyyYyYyyyeyeeeeeeeeeeeUueeeeeYyyeUeMRrYyeyyyY: 


EDIT oldfile 


EDIT oldfile newfile 


OS-9 loads the editor and starts it. The 
initial read file is oldfile. The editor 
creates a file called SCRATCH; this is 
the initial write file. When the edit ses- 
sion is complete, oldfile is deleted, and 
SCRATCH is given the name oldfile. 
This gives the appearance of oldfile 
being updated. 


Note: The two OS-9 utilities DEL and 
RENAME must be present on your sys- 
tem if you wish to start the editor in this 
manner. 


OS-9 loads the editor and starts it. The 
initial read file is oldfile. The editor 
creates newfile, the initial write file. 


The terms oldfile, newfile, and file 
refer to any properly constructed OS-9 
pathlist. 
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2 / Edit Commands 


Displaying Text 


Ln 


lists (displays) the next n lines, starting at the current position of 
the edit pointer. The position of the edit pointer does not 
change. Examples: 


L. (ENTER 
displays the current line. 


If the edit pointer is not at the beginning of the line, only that 
part of the line from the edit pointer to the end of the line is 
displayed. 


L3 (CENTER 


displays the current line and the next two lines. 


L.#* (ENTER 


displays all text from the current position of the edit pointer to 
the end of the buffer. 


The L command displays text regardless of which verify mode is 
in errect: 


Xn 


Displays n lines that precede the edit pointer. The position of the 
edit pointer does not change. Examples: 


* (CENTER 


displays any text on the current line that precedes the edit 
pointer. If the edit pointer is at the beginning of the line, nothing 
is displayed. 


il 


3 (ENTER 


displays the two preceding lines and any text on the current line 
that precedes the edit pointer. 


The X command displays text regardless of which verify mode 
is in effect. 


Manipulating the Edit Pointer 


12 


CLEAR 


moves the edit pointer to the beginning (first character) of the 
text buffer. The screen shows the up arrow when you hold down 


CLEAR) and type (7). Example: 
CLEAR ENTER 


moves the edit pointer to the beginning of the buffer. 


/ 


moves the edit pointer to the end (last character) of the buffer. 
Example: 


/ (ENTER 
moves the edit pointer past the end of the buffer. 


ENTER 


moves the edit pointer to the beginning of the next line and 
displays it. 


This command is useful for going through text one line at atime. 
For example, you may want to look at each line, correct any 
mistakes, and then move to the next line. 


+n 


Moves the edit pointer either to the end of the line or forward n 
lines and displays the line. Entering a value of zero moves the 
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edit pointer to the end of the current line. Example: 
+@ (ENTER 


Entering a value other than zero moves the edit pointer forward 
n lines and displays the line. Examples: 


+ (ENTER 


moves the edit pointer to the next line and displays the line. This 
command performs the same function as (ENTER). 


+1@ (ENTER 
moves the edit pointer forward 10 lines and displays the line. 
+%* (ENTER 


moves the edit pointer to the end of the buffer. 


= 


moves the edit pointer either to the beginning of the line or back 
(toward the top) n lines. Examples: 


-~@ (ENTER 


moves the edit pointer to the beginning of the line and displays 
the line. 


Entering a value other than zero moves the edit pointer back n 
lines. Examples: 


- (ENTER 
moves the edit pointer back one line and displays it. 
-3 (ENTER 


moves the edit pointer back five lines and displays the line. 
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~* (ENTER 
moves the edit pointer to the beginning (top) of the buffer and 
displays the first line. 
>n 


Moves the edit pointer to the right n characters. This command 
is used primarily to move the edit pointer to some position in the 
line other than the first character. Examples: 


> 

moves the edit pointer to the right one character. 
ooo 

moves the edit pointer to the right 25 characters. 
* 


moves the edit pointer to the end of the buffer. 


<n 


moves the edit pointer to the left n characters. This command is 
used primarily to move the edit pointer to some position in a line 
other than the first character. Examples: 


ENTER 
moves the edit pointer to the left one character. 
£10 
moves the edit pointer to the left 10 characters. 
<%* (ENTER 


moves the edit pointer to the beginning of the buffer. 
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Inserting and Deleting Lines 


SPACEBAR) text 


inserts lines you enter from the keyboard. The lines are inserted 
before the current position of the edit pointer. The position of 
the edit pointer does not change. The first character you type is a 
space. Examples: 


SPACEBAR)INSERT THIS LINE (ENTER 
inserts the line. 


SPACEBAR)L. INE ONE (ENTER 
SPACEBAR)L INE TWO (ENTER 
SPACEBAR)L. INE THREE (ENTER 


inserts three lines. 


In str 


Inserts a line of n copies of the string. The line is inserted before 
the position of the edit pointer, and the position of the edit 
pointer does not change. Example: 


14@// (ENTER 
inserts a line containing 80 asterisks. 


This is useful when outlining a portion of text. You can also use 
the **I’? command to insert a line containing a single copy of the 
string. This is important when you want to use a macro to insert 
lines, since the is not used within a macro. Example: 


]*LINE TO INSERT” (ENTER 


inserts the line. 


Dn 


deletes (removes) n lines from the edit buffer, starting with the 
current line. This command displays the lines to be deleted. 
Examples: 


1S 
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D (ENTER 


deletes the current line — regardless of the position of the edit 
pointer — and displays it. 


D4 (ENTER 
deletes the current line and the next three lines. 
D* (ENTER 


deletes everything from the current line to the end of the buffer. 


Kn 


kills (deletes) n characters, starting at the current position of the 
edit pointer. This command displays all deleted characters. 
Examples: 


K (ENTER 
deletes the character at the current position of the edit pointer. 
K 4 (ENTER 


deletes the character at the current position of the edit pointer 
and the next three characters. 


K * (ENTER 


deletes everything from the current position of the edit pointer to 
the end of the buffer. 


En str 


extends n lines by adding a string to the end of each line. This is 
useful, for example, for adding comments to assembly language 
statements. This command extends the line, displays it, and 
then moves the edit pointer past it. Examples: 


E/this is a comment/ (ENTER 


adds the string ‘‘this is acomment’’ to the end of the current line 
and moves the edit pointer to the next line. 
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Searching and 


E3/xXx (ENTER 


adds the string XX to the end of the current line and the next two 
lines and moves the edit pointer past these lines. 


U 


unextends (deletes) the remainder of a line from the current 
position of the edit pointer. This command is commonly used to 
remove extensions, such as comments, from a line. Example: 


U (ENTER 


deletes all the characters from the current position of the edit 
pointer up to the end of the current line. 


For some practice in using the commands that display text, 
manipulate the edit pointer, and insert and delete lines, turn to 
Sample Session 1. 


Substituting 


Sn string 


searches for the next n occurrences of the string. When it finds 
the occurrence, it displays the line, and moves the edit pointer 
past it. If it does not find the string, the edit pointer does not 
move. Examples: 


S/fmy string/ 

searches for the next occurrence of ‘‘my string.” 
S3"strung out" (ENTER 

searches for the next three occurrences of ‘‘strung out.’’ 
S*/seek and find/ 


searches for all occurrences of ‘‘seek and find’’ that are between 
the edit pointer and the end of the text. 
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Cn stringl string2 


changes the next n occurrences of string/ to string2. When it 
finds string], it moves the edit pointer past it and changes 
string! to string2; then it displays the updated line. If it does not 
find string/l, the edit pointer does not move. Examples: 


C/this/that/ 

changes the next occurrence of ‘‘this’’ to ‘‘that.”’ 
C2/in7out/ 

changes the next two occurrences of ‘‘in’’ to ‘‘out.’’ 


Ciseek and find! sought and found! 
ENTER 


changes all occurrences of ‘‘seek and find’’ to ‘‘sought and 
found’’ that are between the edit pointer and the end of text. 


An 


sets the SEARCH/CHANGE anchor to Column n. To find a 
string that begins in Column | (such as an assembly language 
label) but that you don’t want to find if it begins in any other 
column, set the anchor to Column | before using the search 
command to find it. Examples: 


A 

finds a string only if it begins in Column 1. 
AS@ 

finds a string only if it begins in Column 50. 


To return to the normal mode of searching, set the anchor to 
zero. You can now find a string regardless of the column in 
which it begins. Example: 
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A@ (ENTER 


If you use the A command to set the anchor, this setting remains 
in effect only for the current command line. After EDIT ex- 
ecutes the command, the anchor automatically returns to its 
normal value of zero. 


For some practice in using the commands that search and 
substitute, turn to Sample Session 2. 


Miscellaneous Commands 


Tn 


tabs (moves) the edit pointer to Column n of the current line. If n 
exceeds the’ line length, this command extends the line with 
spaces. Examples: 


T (ENTER 
moves the edit pointer to Column | of the current line. 


TS (ENTER 


moves the edit pointer to Column 5 of the current line. 


SHELL command line 


lets you use any OS-9 command from within the editor. The 
remainder of the command line following .SHELL passes to the 
OS-9 Shell for execution. Examples: 


pRHBLtie DIR SOL 

calls the OS-9 Shell to print the directory D1. 
»SHELL BASIC@9S 

starts BASICO9. 
»SHELL EDIT oldfile newfile 


starts another copy of the editor. 
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Mn 


adjusts the amount of memory available for buffers and macros. 
If the workspace is full and the editor does not allow you to enter 
more text, increase the workspace size. If you will use little of 
the available workspace, decrease the workspace size so that 
other OS-9 programs may use the memory that you free. 
Examples: 


MS2ae 

sets the workspace size to 5,000 bytes. 
Migaade 

sets the workspace size to 10,000 bytes. 


Before typing (Q) to quit editing, you may want to increase the 
workspace. This decreases the amount of time needed to copy 
the input file to the output file, since the editor is then able to 
read and write more of the file at one time. Memory is allocated 
in 256-byte pages; therefore, for the M command to have any 
effect, the desired workspace size must differ from the current 
size by at least 256 bytes. The M command does not let you 
return any part of the workspace that is being used for buffers or 
macros. 


SIZE 


displays the size of the workspace and the amount that has been 
used. Example: 


Seek 
arg pipe 3 8 


52] is the amount of workspace used for buffers and macros. 
15328 is the amount of memory available in the workspace. 


Q 


ends editing and returns to the OS-9 Shell. 


If you specified files when you started the editor, the text in 
Buffer 1 is written out to the initial write file (the one you 
specified when you started EDIT). The remainder of the initial 
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input file (the one you specified when you started EDIT) is then 
copied to the initial write file. After the text is copied, the editor 
terminates and control returns to the OS-9 Shell. 


Vmode 


turns the verify mode on or off. When you start the editor, the 
verify mode is on; therefore, the editor displays the results of all 
commands for which results can be displayed. If you do not 
want to see the results of commands, turn off the verify mode by 
specifying 0 (zero) for mode. Example: 


(J@ (ENTER 
turns off the verify mode. 


To return to the verify mode, specify any nonzero value for 
mode. Examples: 


We 

turns on the verify mode. 
Wis 

turns on the verify mode. 


If the verify mode is on and you switch to a macro, it remains 
on. If you turn off the verify mode while in the macro, it is 
automatically restored when you return to the editor. 


_ Manipulating Multiple Buffers 


.DIR 


displays the directory of the editor’s buffers and macros, which 
is similar to the one below: 


BUFFERS: 
$ @ (secondary buffer) 
¥% 1 (Primary buffer) 


28 (another buffer) 
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MACROS: 


MYMACRO 
Lior 
COPY 


Bn 


makes buffer n the primary buffer. When you switch from one 
buffer to another, the old one becomes the secondary buffer and 
the new one becomes the primary buffer. Example: 


BS (ENTER 


makes Buffer 5 the primary buffer; if Buffer 5 does not exist, it 
is created. 


Pn 


puts (moves) n lines into the secondary buffer. This command 
removes the lines from the primary buffer, starting at the posi- 
tion of the edit pointer and inserts them into the secondary buffer 
before the current position of the edit pointer. It displays the text 
that is moved. Examples: 


P 

moves one line to the secondary buffer. 
PS 

moves five lines to the secondary buffer. 
P# 


moves to the secondary buffer all lines that are between the 
current position of the edit pointer and the end of text. 


Gn 


gets (moves) n lines from the secondary buffer. This command 
takes the lines from the top of the secondary buffer and inserts 
them into the primary buffer before the current position of the 
edit pointer. It displays the lines that are moved. When used 
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with the P command, the G command moves text from one 
place to another. Examples: 


G 

gets one line from the secondary buffer. 
GS 

gets five lines from the secondary buffer. 
G* 

gets all lines from the secondary buffer. 


For some practice in using miscellaneous commands and the 
commands that manipulate multiple buffers, turn to Sample 
Session 3. 


Text File Operations 


This section of the manual describes the group of commands 
related to reading and writing OS-9 text files. 


.NEW 


gets new text. This command is used when editing a file that is 
too large to fit into the editor’s workspace at one time. .NEW 
writes out all lines that precede the current line and then the 
editor tries to read in an equal amount of new text that is 
appended to the end of the buffer. 


The NEW command always writes text to the initial output file 
(the one created when you started the editor) and always reads 
text from the initial input file (the one specified when you 
started the editor). 


If you have finished editing the text currently in the buffer, you 
may ‘‘flush’’ out this text and fill the buffer with new text by 
moving the edit pointer to the bottom of the buffer and then 
using the .NEW command. Example: 


/,NEW (ENTER 
23 
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If you wish to retain part of the text that is already in the buffer, 
move the edit pointer to the first line you wish to retain and then 
type (-) NEW. This ‘‘flushes’’ out all lines that precede the edit 
pointer. It then tries to read in new text that is the same size as 
the portion flushed out. 


~READ str 


prepares an OS-9 text file for reading; str specifies the pathlist. 
Example: 


*READ "myfile" (ENTER 
closes the current input file and opens ‘‘myfile’’ for reading. 
You may specify an empty pathlist. Example: 


»*READ "" (ENTER 


closes the current input file and restores the initial input file (the 
one you specified when you started the editor) for reading. 


An open file remains attached to the primary buffer until you 
close the file. You may have more than one input file open at 
any time by using the .READ command to open them in differ- 
ent buffers. 


To read these files, switch to the proper buffer, and then use the 
R command to read from that buffer’s input file. To close a file: 
you must be in the same buffer in which the file was opened. 


WRITE str 


opens a new file for writing. The string specifies the pathlist for 
the file you wish to create. Example: 


»WRITE "“newfile" 
closes the current write file and creates one called ‘‘newfile.”’ 
You may specify an empty pathlist. Example: 

cAI TE Ys 


closes the current write file and restores the initial write file (the 
one you specified when you started the editor). 
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A new write file is attached to the primary buffer and remains 
attached until you close the file. You may have more than one 
write file open by using the .WRITE command to open them in 
different buffers. To write these files, switch to the proper 
buffer and then write that buffer’s file. To close a file, you must 
be in the same buffer in which the file was opened. 


Rn 


reads (gets) n lines of text from the buffer’s input file. It displays 
the lines and inserts them before the current position of the edit 
pointer. Examples: 


R 
reads one line from the input file. 
FR i@ (ENTER) 
reads 10 lines from the input file. 
R* 
reads the remaining lines from the input file. 
If a file contains no more text, the screen shows the *END OF 
FILE* message. 
Wn 


writes n lines to the output file, starting with the current line. It 
displays all lines that are deleted from the buffer. Examples: 


ll CENTER 


writes the current line to the output file. 


WS (ENTER 


writes the current line and the next four lines to the output file. 


ix (ENTER 


writes all lines from the current line to the end of the buffer to the 
output file. 
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For some practice in using the commands that read and write 
OS-9 text files, turn to Sample Session 4. 


Conditionals and Command Series Repetition 


When a command cannot be executed, the editor sets an internal 
flag, and the screen shows FAIL. For example, if you try to read 
from a file that has no more text, the editor sets the fail flag. 
After the fail flag is set, the editor will not execute any more 
commands until one of the following conditions is met: 


L 


The end of a command line is reached if it was typed 
in from the keyboard. 


The end of the current loop is reached. Any loops 
that are more deeply nested will be skipped. (See 
the repeat command. ) 


A colon (:) command is encountered. Since loops 
that are nested deeper than the current level are 
skipped, any occurrences of : that are in a more 
deeply nested loop will also be skipped. 


Below are commands that set the fail flag and the condition on 
which it is set: 


= 


S,C 


P,W 


Trying to move the edit pointer beyond the begin- 
ning of the edit buffer. 


Trying to move the edit pointer beyond the + end 
of the buffer. 


Not finding a string that was searched for. 
No text left in the secondary buffer. 
No text left in the read file. 


No text left in the primary buffer. 


If you specify an asterisk for the repeat count on these com- 
mands, the fail flag is not set. This is because an asterisk usually 
means continue until there is nothing more to do, and the 


26 


eeeeeee ego oeoeooeoeoeoeoeoeeoeeoeeoeoeeeeoeeoeeee eee e @ ea 


WREEEEEREEREEREEE EEE eeeeeeeeeeereey 


commands succeed in doing just that. In addition to these 
commands that set the fail flag as a side effect, the following 
commands explicitly set the fail flag if some condition is not 
true. 


.EOF 


tests for end of file. This succeeds if there is no more text to read 
from the file; otherwise, it sets the fail flag. 


.NEOF 


tests for not end of file. This succeeds if there is text to read from 
the file; otherwise, it sets the fail flag. 


-EOB 


tests for end of buffer. This succeeds if the edit pointer is at the 
end of the buffer; otherwise, it sets the fail flag. 


.NEOB 


tests for not end of buffer. This succeeds if the edit pointer is not 
at the end of the buffer; otherwise it sets the fail flag. 


-EOL 


tests for end of line. This succeeds if the edit pointer is at the end 
of the line; otherwise, it sets the fail flag. 


.NEOL 


tests for not end of line. This succeeds if the edit pointer is not at 
the end of the line; otherwise, it sets the fail flag. 


ZERO n 


tests for zero value. This succeeds if n equals zero; otherwise, it 
sets the fail flag. 
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STAR n 


tests for star (asterisk). This succeeds if n equals 65,535 (‘‘*’’) 
otherwise, it sets the fail flag. 


2 


STR str 


tests for string match. This succeeds if the characters at the 
current position of the edit pointer match the string; otherwise, it 
sets the fail flag. 


-NSTR str 


tests for string mismatch. This succeeds if the characters at the 
Current position of the edit pointer do not match the string; 
otherwise, it sets the fail flag. 


ne) 

exits and succeeds. This is an unconditional exit from the 
innermost loop or macro. The fail flag clears after the exit. 
.F 

exits and fails. This is an unconditional exit from the innermost 
loop or macro. The fail flag sets after the exit. 

[commands | n 


repeats the commands n times. Left and right brackets form a 
loop that repeats the enclosed commands n times (the loop must 
be repeated at least once). If the loop is entered from the 
keyboard, it must all be on one line. If it is part of a macro, 
however, it may span several command lines. Examples: 


[ L 1 35 (ENTER 
repeats the L command five times. 


Note: This is not exactly the same as LS, which executes the L 
command only once and has 5 as its parameter. 
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[+1 (ENTER 


displays lines starting with the next line up to the end of the 
buffer and moves the edit pointer to the end of the buffer. 


This command repeats the + command until the end of the 
buffer is reached. Then when the command tries to move the 
edit pointer past the end of the buffer, the fail flag is set; this 
terminates the loop and clears the fail flag. 


Whenever the end of the loop is reached and the fail flag is set, 
the current loop is terminated and the fail flag is cleared. 


: commands 


decides whether or not to execute the commands that follow it, 
depending on the state of the fail flag. Below are the actions 
taken as a result of the colon (:) being executed and the state of 
the fail flag. 


Skips all commands that fol- 
low the colon (:) up to the end 
of the current loop or macro. 


FAIL FLAG CLEAR 


Clears the fail flag and ex- 
ecutes the commands that fol- 
low the colon (:). 


FAIL FLAG SET 


Below is a command line that deletes all lines that do not begin 
with the letter A. 


CLEAR)(7 ) r ,NEOB r ,STR"A" + 
Oo] 2 * 


The moves the edit pointer to the beginning of the buffer. 
The outer loop tests for the end of the buffer and terminates the 


loop when it is reached. 


The inner loop tests for n A at the beginning of the line. If there 
is one, the + command is executed; otherwise, the D command 
is executed. 


Below is acommand that searches the current line for “Tanai.” 
If the command finds ‘‘find it,’’ the screen shows the line. 
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Edit Macros 
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Otherwise, the command line fails and the screen shows 
“PAIL. 


CL wEOL VO «-O@ VY JF +s sSTR"find it" 
“Ye 2 ES ae 


-EOL VO -0 V .F tests to determine if the edit pointer is at the 
end of the line. If it is, the verify mode is turned off to prevent 
the -O from displaying the line. Then it is turned back on, and the 
.F ends the loop. 


If the edit pointer is not at the end of the line, the .STR command 
searches for ‘find it’’ at the current position of the edit pointer. 
If it is at the end of the line, the -0 .S commands are executed. 
This moves the edit pointer back to the beginning of the line, 
displays the line, and terminates the loop. Otherwise, the > 
command moves the edit pointer to the next position in the line. 


The brackets prevent the command from failing and terminating 
the main loop if the end of the buffer is reached. 


‘‘Edit macros’’ are commands you create to perform a special- 
ized or complex task. For example, you can replace a frequently 
used series of commands with a single macro. First, save the 
series in a macro. Then each time you need it, type a period 
followed by the macro’s name and parameters. The editor 
responds as if you had typed the series of commands. 


Macros consist of two main parts — the header and the body. 
The header gives the macro a name and describes the type and 
order of its parameters. The body is made up of any number of 
ordinary commands (except for and (ENTER), any 
command may be used in a macro). Note: Macros cannot create 
new macros. 


To create a macro, first define it with the .MAC command. 
Then enter the header and body just as you would enter tett into 
an edit buffer. When you are satisfied with the macro, close its 
definition by typing (Q). This returns you to the normal edit 
mode. 
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Macro Headers 


Parameter Passing 


A macro header must be the first line in each macro. It is made 
up of a name, which may be followed by a “‘variable list’’ that 
describes the macro’s parameters if there are any. The name 
consists of any number of consecutive letters and underline 
characters. Examples: 


MACRO 

trim—_spaces 

LIST 
EXTRA_LONG_MACRO_NAME 


Although you may make a macro name any length, it is better to 
keep it short because you must spell it the same each time you 
use it. You may use upper- and lower-case letters or a mixture. 


Like other commands, macros may be given parameters so that 
they are able to work with different strings and numbers of 
things. Macros are unable to use parameters directly; instead, 
the parameters are passed on to the commands that make up the 
macro. 


To pass the macro’s parameters to these commands, use the 
variable list in the macro header to tell each command which of 
the macro’s parameters to use. Each variable in the variable list 
represents the value of the macro parameter in its corresponding 
position. Use the corresponding variable wherever the param- 
eter’s value is needed. 


The two types of variables are numeric and string. A numeric 
variable is a variable name preceded by the # character. A 
string variable is a variable name preceded by a $ character. 
Variable names, like macro names, are composed of any num- 
ber of consecutive letters and underline characters. Examples of 
numeric variables: 


#N 
# ABC 
#LONG_NUMBER_VARIABLE 
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Examples of string variables: 


$A 

$B 

$STR 

$STRLA 
$lower-case_variable_name 


The function of the edit macro below is the same as that of the S 
command — to search for the next n occurrences of a string. The 
first line of the macro is the macro header; it declares the 
macro’s name to be SRCH. It also specifies that the macro needs 
one numeric parameter (#N) and one string parameter (S$STR). 
The entire body of the macro is the second line. Here both of the 
macro’s parameters are passed to the S command, which does 
the actual searching. 


SRCH #N $STR 
S #N $STR 


Below is an example of how to execute this macro: 
-SRCH 15 “‘string’’ 


In the next example the order of the parameter is reversed. 
Therefore, when executing the macro, use the reverse order. 
Below is the macro definition: 


SRCH $STR #N 
S #N $STR 


Specify the parameters for the ‘‘S’? command in the proper 
order since it is only the ‘‘SRCH’’ macro that is changed. Below 
is an example of how to execute this macro. The order of the 
parameters directly corresponds to the order of the variables in 
the variable list. 


SRCH “‘string’”’ 15 


! text 


places comments inside a macro. Ignore the remainder of the 
line following the ! command. This allows you to include, as 
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part of a macro, a short description of what it does in case you 
forget or in case someone else wants to use the macro. 
Examples: 


| 


(4)! Move the edit pointer to the top of the buffer. 


L* ! Display all lines of text. 
! 


In the example above are four comments; two are empty, and 
two describe the commands that precede them. 


macro name 


executes the macro specified by the name following the period 
(.). Examples: 


.MYMACRO 

.LIST 0 

fae (aan 

MERGE °° FILE_WA * FILE: B B”’ 


-~MAC str 


creates anew macro or opens the definition of an existing one so 
that it may be edited. To create a new macro, specify an empty 
string. Example: 


»>MAC // (ENTER 
creates a new macro and puts you into the macro mode. 


The screen shows M: instead of E: when the editor is in the 
macro mode. To edit a macro that already exists, specify the 
macro’s name. Example: 


*MAC "MYMACRO" (ENTER) 
opens the macro ‘‘“MYMACRO”’ for editing. 


When a macro is open, edit it or enter its definition with the 
Same comands you use in a text buffer. After you edit the macro, 
type CQ) to close its definition and return to the edit mode. The 
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first line of the macro must begin with a name that has not 
already been used in order to close the definition and return to 
EDIT. 


SAVE strl1 str2 


saves macros on an OS-9 file. String/ specifies a list of macros 
to be saved; the macro names are separated by spaces. String2 
specifies the pathlist for the file on which the macros are to be 
saved. Examples: 


SAVE ‘SMYMACRO’’MYFILE’”’ 
saves the macro ‘‘MYMACRO’’ on the file ‘‘MYFILE.’’ 
SAVE ‘‘SMACA MACB MACC’’MFILE 


saves the macros ‘‘MACA,”’’ ‘‘MACB,”’ and ‘‘MACC’’ on the 
file ‘“MFILE.”’ 


To save more than one macro on a file, space between their 
names. 


SEARCH un str 


searches the text file buffer for the specified string. When a 
match is found, it stops and displays that line. The n option 
permits a search for the nth occurrence of a string match. This 
command is the same as S n str.,LOAD str. 


loads macros from an OS-9 file. As each macro is loaded, EDIT 
verifies that no other macro exists with that name. A duplicate 
name does not load, and EDIT skips to the next macro on the 
file. EDIT displays the names of all macros it loads. Examples: 


»+LOAD "MACROFILE" 
loads the macros in the file called MACROFILE. 
»>LOAD "MYFILE™"™ (ENTER 


loads the macros in the file called MYFILE. 
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~DEL str 

deletes the macro specified by the string. Examples: 
»DEL "MYMACRO" (ENTER 

deletes the macro called MYMACRO. 
,OEL “i167: (ENTER 


deletes the macro called LIST. 


.DIR 


displays the current edit buffer area. All edit buffers and macros 
currently in memory are displayed. 


-CHANGE nu str1 str2 


changes the occurrence at string] with string. The n option 
permits n occurrences at string] to be changed with string2. 


Q 


ends a macro edit session. It returns you to the normal edit 
mode. 


Example: 


Search_and_Delete #N $STR 

! This example MACRO is used to check the string at the 
beginning of an #N number of lines. 

! If the string matches, it will delete that line from the text 
buffer file. 


! NOTE: The way the editor processes a MACRO causes it to 
see any parameters in the outer loop first. Thus, the #N 


parameter is processed before the STR parameter. 


Ch) 'Move to start of edit buffer 
[ !start of outer loop 
.NEOB 'test for buffer end 
[ 'start of inner loop 


.NSTR $STR __!test for not string match 


a 


_ ese 
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7 !'go to next line if no match 

lif flag clear skip next command 
D 'delete line if flag set 

| 'end of inner loop 

J#N 'end of outer loop 


! End of Macro 


For some practice in using macro commands, turn to Sample 
Session 5. 
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3 / Sample Sessions 


Sample Session 1 


Clear the buffer by deleting its contents. 
You Type: (CLEAR)7D* (ENTER 
Screen Shows: E:(4) 


Insert three lines into the buffer. Begin each line with a space, 
which is the command for inserting text. 
You Type: (SPACEBAR)MY FIRST LINE 
(SPACEBAR)MY SECOND LINE 
(SPACEBAR)MY THIRD LINE 
Screen Shows: E: MY FIRST LINE 
E+: MY SECOND EINE 
Sey THe LIne 


Move the edit pointer to the top of the text. The editor always 
considers the first character you type acommand. Note: 
7 always shows on the screen. Typing © *) also moves the 
edit pointer to the beginning of a buffer. 

You Type: (CLEAR)7 (ENTER) 

Screen Shows: E: 


List (display) the first line you inserted into the buffer. 
You Type: L. 
Screen Shows: E:L 
MY FIRST LINE 


Display the first two lines you inserted into the buffer. 
You Type: L2 (ENTER 
Screen Shows: E: Le 
MY FIRST LENE 
MY SECOND LIne 


Move to the next line and display it. 
You Type: 
Screen Shows: E: 
MY SECOND LINE 


Move to the next line and display it. 
You Type: 
Screen Shows: E: 
MY THIRD Loss 


RF 
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Display text beginning at the position of the edit pointer. This is 
the function of L. 
You Type: L 
Screen Shows: E: Ll 
MY THIRD LINE 


Insert a line into the buffer. Note: In the next sample you will 
see that the line is inserted before the current position of the edit 
pointer. 
You Type: (SPACEBAR) INSERT A LINE 
Screen Shows: E: INSERT A LINE 


The following command line consists of more than one com- 
mand. (CLEAR)7 (4) moves the edit pointer to the top of the text. 
L displays the text, and the asterisk (*) following L indicates 
that text is displayed through to the end of the buffer. 
You Type: (CLEAR)7L + 
Screen Shows: E:(4)L# 
Y FIRST LINE 
MY SECUND LINE 
INSERT A LINE 
MY THIRD LINE 


Show the position of the edit pointer. 
You Type: L 
Screen Shows: E:L 
mY PIRST LINE 


Move the edit pointer forward two lines and display the lines. 
You Type: +2 (ENTER 
Screen Shows: E: +2 
INSERT A LINE 


Display all lines from the edit pointer to the end of the buffer. 
You Type: L¥ 
Screen Shows: E:L+# 
INSERT A LINE 
MY PHIRD LINE 


Move the edit pointer to the end of the buffer. 
You Type: / (ENTER 


Screen Shows: E: / 


Show that the edit pointer is at the end of text. It is, since the 
screen shows no lines. 


e@eeeee ee oe oeoeoeoeee ooo eoeoeeeoeeeoeoeoe ee ee @ @ a 
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You Type: .* (ENTER 


Screen Shows: E:l¥* 


Insert two more lines. 
You Type: (SPACEBAR)F IFTH LINE 
(SPACEBAR)LAST LINE 
Screen Shows: E: FIFTH LINE 
E: LAST LINE 


Move the edit pointer back one line and display the line. 
You Type: -2 (ENTER 
Screen Shows: E: -< 
PIFTH LING 


Move the edit pointer back two lines and display the line. 
You Type: -3 
Screen Shows: E:-3 
MY SECOND LINE 


Move the edit pointer three characters to the right and display 
the remainder of the line. Note: Space between commands. 
You Type: #3 L 
Screen Shows: E: 23 L 
SECOND LINE 


Display the characters that precede the edit pointer on the 


current line. 
You Type: * (ENTER 


Screen Shows: E: x 
MY 


Move the edit pointer to the end of the current line. 
You Type: +@ (ENTER 


Screen Shows: E:+@ 


Show that the edit pointer is at the end of the line. It is, since the 
screen shows no lines. 


You Type: L (ENTER 


Screen Shows: E: Ll 


Display the characters that precede the edit pointer on the 
current line. 
You Type: X (ENTER 
Screen Shows: E: 4 
MY SECOND LINE 
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Move the edit pointer back to the beginning of the current line. 
You Type: -@ 
Screen Shows: E: -@ 
MY SECOND LINE 


Show that the edit pointer is at the beginning of the line. It is, 
since the screen shows no lines. 
You Type: * (ENTER 


\¢ 


Screen Shows: E: X 


Go to the beginning of the text. 
You Type: (CLEAR)? (ENTER 
Screen Shows: E: (4) 


Insert a line of 14 asterisks. 
You Type: 114"%*" (ENTER 


Screen Shows: E:1[i4"*" 
KEKEKHKKKEEKHKEES 


Insert an empty line. 
You Type: I"" (ENTER 
Screen Shows: E: I" " 


Move to the top of the text and display all lines in the buffer. 
You Type: (CLEAR)7L * (ENTER 


Screen Shows: E:(4)L+* 
KEKEKHKKERKKREKEESE 


MY Finks! 21Ne 
MY SECOND LINE 
INSERT A LINE 
MY THER 2INe 
Pirin LIN 
LAST LINE 


Move the edit pointer forward two lines. 
You Type: +2 (ENTER 
Screen Shows: E: +2 
MY FIRST LINE 


Extend the line with XXX. 
You Type: E" XXX" (ENTER 
Screen Shows: E:E" XK" 
mY FIRST LINE KAR 


SOOOCHCHOOCHSOSHOHSHOOOSHOOOHOHOSOHOOSOCOHOOOOOCOCEECE 


9000000000008 HHHHHHHHHHHHH88EEO 


Display the current line. Note: The previous E command moved 
the edit pointer to the next line. 
You Type: L 
Screen Shows: E:L 
MY SECOND LINE 


Extend three lines with YYY. 
You Type: E3" (SPACEBAR)*’ *’ ¥ " 
Screen Shows: E:E3" YY" 
MY SECOND LINE YYY¥ 
INSERT A LINE YY¥ 
MY THIRD LINE YY* 


Move back 2 lines. 
You Type: -2 (ENTER 
Screen Shows: E:-2 
INSERT A LINE ‘Y**¥ 


Move the edit pointer to the end of the line; move the edit pointer 
back four characters; display the current line, starting at the edit 
pointer. 
You Type: +@ #4 L 
Screen Shows: E:+@ “4 L 
i ik de 3 
Truncate the line at the current position of the edit pointer. This 
removes the YYY extension. 
You Type: U 
Screen Shows: E:U 
INSERT A LINE 


Go to the top of the text and display the contents of the buffer. 


You Type: (CLEAR)7.* (ENTER 


Screen Shows: E:(4)L* 
KEE ERHKEEEEEREEE 


MY FIRST LINE AAA 
MY SECOND LINE YY* 
INSERT A LINE 

¥ THIRD LINE YY 
FIFTH LINE 

LAST LINE 
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Delete the current line and the next line. 
You Type: D2 (ENTER 
Screen Shows: E:D2 
KEKE KKHKEKKHESE 


Move the edit pointer forward two lines. 
You Type: +2 (ENTER 
Screen Shows: E:+2 
INSERT A LINE 


Delete this line. 
You Type: D 
Screen Shows: E:D 
INSERT A LINE 


Display the current line. 


You Type: L (ENTER 
Screen Shows: E: MY THIRD LINE YY¥ 


Move the edit pointer to the right three characters and display 
the text. 
You Type: *3 L (ENTER 
Screen Shows: E: 33 L 
THIRG LINE YY 


Kill (delete) the 11 characters that constitute THIRD LINE. 
You Type: Kili 
Screen Shows: E:kK1i1 
THIRD LINE 


Go to the beginning of the line and display it. 
You Type: -@ 
Screen Shows: E: -@ 
M4 ¥ x 4 x 
Concatenate (combine) two lines. Move the edit pointer to the 
end of the line; delete the character at the end of the line; move 
the edit pointer back to the beginning of the lines. Display the 
line. 
You Type: +@ K -@ (ENTER 
Screen Shows: E: +@ K -@ 
MY VYVYPLPTH LINE 


@9@eeeooeoeode eee eeeeeeeoeeeoeeeeeeee eee eee @ @ 


RBRRERERRERERRERERERRRERRRRERRERRAEERSE SE 


Separate the two lines by inserting an end-of-line character. 
You Type: =6 I// 
Screen Shows: E: 26 I[// 
M é § Ff kd : 
Note: The empty line is inserted before the current position of 
the edit pointer. 
You Type: L 
Screen Shows: E:L 
PIFTH LOWE 


Sample Session 2 


Clear the buffer by deleting its contents. 
You Type: (CLEAR)7D* (ENTER 
Screen Shows: E:(4)D# 


Insert lines. 
You 


Type: GPACEBARONE TWO THREE 1.8 
(SPACEBAR)ONE 
(SPACEBAR)(SPACEBAR) T WO 

THREE 
(SPACEBARNONE TWO THREE 2 +@ 
(SPACEBAR)ONE 
(SPACEBAR)(SPACEBAR) T WO 
THREE 
(SPACEBARONE TWO THREE 3.0 
Screen Shows: E: ONE TWO THREE 1.8 
ONE 
TWO 
THREE 
ONE TWO THREE 2.9@ 
ONE 
TWO 
THREE 
ONE TWO THREE 3.90 


mmm mmamm mM 
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Ae 


Go to the top of the text and display all lines in the buffer. 
You Type: (CLEAR)7.* (ENTER) 
Screen Shows:0E: C4)L¥* 

ONE TWO THREE 1.92 
ONE 
TWO 
THREE 
ONE TWO THREE 2.8 
ONE 
TWO 
THREE 
ONE TWO THREE 3. 


Search for the next occurrence of TWO. The edit pointer moves 
past the letter O in TWO; the entire line is found and displayed. 
You Type: .S "TWO" (ENTER 
Screen Shows: E:S" TWO" 
ONE TWO THREE 1.84 


Show that the edit pointer has moved. 
You Type: L 
Screen Shows: E:L 
Thiet Lae 


Search for all occurrences of ‘‘TWO’’ that are between the edit 
pointer and the end of the buffer. When ‘‘TWO’”’ is found, the 
edit pointer moves past it and the line is displayed. 
You Type: .S*/TWO/ 
Screen Shows: E:5*/TWO/ 
ONE TWO THREE 1.9 
THO 
ONE TWO THREE 2.0 
THO 
ONE TWO THREE 3.0 


Go to the top of the buffer and change the first occurrence of 
THREE to ONE. 
You Type: CLEAR)? .CHANGE/THREE/ONE/ 
ENTER 
Screen Shows: E : C/THREE/ONE/ 
ONE TWO ONE 1,2 


wWwyryyyyerrryryyryryyyyryryyryyryyyryryrryryyyueryyy i 


Show that the edit pointer has moved past the string that was 
changed. 
You Type: L 
Screen Shows: E:L 
1.@ 


Move the edit pointer to the top of the buffer. Set the anchor to 
Column 2 and then use the search command to find each 
occurrence of TWO that begins in Column 2. All other occur- 
rences are skipped. 
You Type: (CLEAR)? AZ S*/THO/ 
Screen Shows: E:(4) AZ S*¥/THO/ 
TWO 
TWO 


Move the edit pointer to the top of the buffer. Set the anchor to 
Column 1, and change each occurrence of ONE that begins in 
that column to XXX. Note: ONE in Line | is not changed, since 
it does not begin in Column 1. 
You Type: (CLEAR)? AC*¥/ONE/XXX/ 
Screen Shows: E: AC¥/ONE/XXX 
TWO ONE 1,90 


TWO THREE 2.@ 


See et tt 
Fe al le oak oat 
rata eae ve ea ea 
et 
ee ee ee ed 
Pha al le ol ai 


TAG THREE O6@ 


THREE 
XX TWO THREE 3.@ 


s, 


f 
fy 


Go to the top of the buffer and display the text. 
You Type: (CLEAR)7..* (ENTER) 
Screen Shows: E:(4)L+* 
AAA TWO ONE 1.0 


a 
é 


o o re! 


s 
é 


TWO 


Ne 
VFN 
fous 
Vey 
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Change the remaining ONE to XXX. Note: The anchor is no 

longer set. It is reset to zero after each command is executed. 
You Type: ~.-CHANGE /ONE/KAAK/ 

Screen Shows: E:C/ONE/AAK 

XKK TWO KAKA 1.0 


“es 


Move to the beginning of the current line. 
You Type: -@ 
Screen Shows: E:-@ 
XKK THO XKA 1,48 


Change three occurrences of ‘““XXX’’ to “‘ZZZ.”’ 
You Type: .C3/XKK/Z22/ (ENTER 
Screen Shows: E:C3/AKK/<e 

THO AX 

THO 22 


Pd Pa PA 
Po Pa PA 
Po Po Pd 


Sample Session 3 


Clear the buffer by deleting its contents: 


You Type: (CLEAR)7D* (ENTER 
Screen Shows: E:(4)D¥* 


Display the directory of buffers and macros. The dollar sign ($) 
identifies the secondary buffer as Buffer 0; the asterisk (*) 
identifies the primary buffer as Buffer 1. No macros are defined. 
This is the initial environment when EDIT is started from OS-9. 
You Type: .DIR (ENTER 
Screen Shows: E:.DIR 


BUFFERS: 


$ Q 
* 1 
MACROS: 


Insert some lines into Buffer 1 so that later you can identify it. 
You Type: (SPACEBARNBUFFER ONE 1.2 
(SPACEBAR)BUFFER ONE 2.2 
(SPACEBARNBUFFER ONE 3.8 
(SPACEBAR)BUFFER ONE 4.@ 


o@e2e@ee080080e0ee00eeeeeeeeeeeeeeeeeeeee @ @ é 
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Screen Shows: E: BUFFER ONE 1 
E: BUFFER ONE 2 
E: BUFFER ONE 3. 
E: BUFFER ONE 4 


Display the text in Buffer 1. 
You Type: (CLEAR)7L * 
Screen Shows: E:C4)L¥* 
BUFFER ONE 4 
BUFFER ONE 2 
BUFFER ONE 3. 
BUFFER ONE 4 


Make Buffer 0 the primary buffer. Buffer 1 becomes the second- 
ary buffer. 

You Type: B@ 

Screen Shows: E:6@ 


Display the directory of buffers and macros. Note: The symbols 
identifying the buffers are now reversed. 

You Type: .DIR (ENTER 

Screen Shows: E:.DIR 


BUFFERS: 
$ 1 
* Q 


MACROS: 


Insert some lines into Buffer 0. 

You 

Type: (SPACEBARBUFFER ZERO i 

(SPACEBARBUFFER ZERO 2 

(SPACEBARNBUFFER ZERO 3. 

(SPACEBARIBUFFER ZERO 4 

Screen Shows: E: BUFFER ZERO 

E: BUFFER ZERO 

Es BUFFER ZERO 

E: BUFFER ZERO 


mr 
= 
of 
mri 
= =] 


* ++ 


A 


bWhMeE SS SS 
ss Ss Sm mm 
=| || 
—j| || | 
Pry iPr) orn 


al 


Display the text in Buffer 0. 
You Type: (CLEAR)7L. * 
Screen Shows: E:(4)L# 
BUFFER ZERO 1,90 
BUFFER ZERO 2.9 
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BUFFER £ERC: 340 
DUPPER 2e80 -ds@ 


Switch to Buffer 1. 
You Type: B (ENTER 


Screen Shows: E:8 


Display the text in Buffer 1. 
You Type: (CLEAR)7L +* 
Screen Shows: E:(4)L* 
BUFFER ONE i 
BUFFER ONE 2 
OUPFER ONE <3. 
BUPPER UNE. 4 


Move the edit pointer to Line 3 in this buffer. 
You Type: +2 (ENTER 
Screen Shows: E: +2 
BUFFER ONE 3.08 


Switch to Buffer 0. 
You Type: B@ (ENTER 
Screen Shows: E:8@ 


Display the text in Buffer 0. 
You Type: .* (ENTER 
Screen Shows: E:L+¥ 

PUPPER 2ERG 1+ 

BUFFER ZERO 2,90 

DUFFER ZERO 3. ¢ 

DUFFER ZERO 44 


Move the edit pointer to Line 2 in this buffer. 
You Type: + (ENTER 


Screen Shows: E:+ 
BUFFER ZERO 2,98 


Switch to Buffer 1. 
You Type: B (ENTER 


Screen Shows: E:8 


Display the text in Buffer | from the current position of the edit 
pointer. Note: The position of the edit pointer has not changed 


since you switched to Buffer 0. 


You Type: ..* (ENTER 


©@@0e2ee00080808eeeeeeeeeeeeeeeeeeeeeeed@ @ ee 


ryyyryrryrrrereereeeeeeeeeeeeeeeeereereeyy 


Screen Shows: E:L¥* 
BUFFER ONE 3.8 
BUFFER ONE 4.90 


Switch to Buffer 0. 
You Type: B@ (ENTER 
Screen Shows: E:B@ 


Display the text in Buffer 0 from the current position of the edit 
pointer. Note: The position of the edit pointer has not changed 
since you switched to Buffer 1. 
You Type: .* (ENTER 
Screen Shows: E:L¥* 
BUFFER ZERO 2+@ 
BUFFER ZERO 3.98 
BUFFER ZERO 4.8 


Delete the contents of Buffer 0. 
You Type: (LEAR)7D* (ENTER) 
Screen Shows: E:(4)D¥* 
BUFFER ZERO 1,.¢ 
BUFFER ZERO 2.@ 
BUFFER ZERO 3.@ 
BUFFER ZERO 4.9 


Make Buffer 1 the primary buffer and Buffer 0 the secondary 
buffer. 
You Type: B (ENTER 


Screen Shows: E:8 


Move two lines from the primary buffer (Buffer 1) into the 
secondary buffer (Buffer 0). 
You Type: (CLEAR)7P2 (ENTER) 
Screen Shows: E:(4)P2 
BUFFER ONE 1,9 
BUFFER ONE 2,.@ 


Switch to Buffer 0 and show that the lines were moved to it. 
You Type: B@ (CLEAR)7L* (ENTER) 
Screen Shows: E:B8@ C4)L* 
BUFFER ONE 1,.@ 
BUFFER ONE 2,0 


Switch to Buffer 1. Go to the bottom of the buffer and get the 
text out of the secondary buffer. 
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You Type: B / G+ 

Screen Shows: E:B / G¥ 
BUFFER ONE 1.9@ 
BUFFER ONE 2.@ 


Show the contents of the buffer. Note: The order of the lines is 
changed as a result of moving the text. 
You Type: (CLEAR)7L* (ENTER) 
Screen Shows: (4)L.* 
BUFFER ONE 3.6 
BUFFER ONE 4.90 
BUFFER ONE 1.8 
BUFFER ONE 2.8 


Move two lines into the secondary buffer. 
You Type: P2 (ENTER 
Screen Shows: E:P2 
BUFFER ONE 3.2 
BUFFER ONE 4,94 
Move to the bottom of the buffer and get the lines back out of the 
secondary buffer. 
You Type: / G* 
Screen Shows: E:/ G¥*¥ 
BUFFER ONE 3.94 
BUFFER ONE 4.8 


Show that the order of the lines is restored. 
You Type: (CLEAR)7L * 
Screen Shows: E:(4)L¥* 
BUFFER ONE 1.04 
BUFFER ONE 2.0 
BUFFER ONE 3s¢ 
BUFFER ONE 4.@ 
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Sample Session 4 


Enter some lines of text. 
You Type: (SPACEBAR)LINE ONE 
(SPACEBAR)SECOND LINE OF TEXT 
ENTER 
(SPACEBAR) THIRD LINE OF TEXT 
ENTER 
(SPACEBAR)FOURTH LINE 
(SPACEBAR)F IF TH LINE (ENTER 
(SPACEBARLAST LINE 
Screen Shows: E: LINE ONE 
Ee SELUND LINE OF TERT 
THIRD LINE OF TEXT 
FOURTH LINE 
PIFTH LINE 
Ee LAST LINE 


m7] 7 Mm 


Open the file ‘‘oldfile’’ for writing. 
You Type: »>WRITE"“oldfile" (ENTER 
Screen Shows: E: -WRITE"oldfile" 


Write all lines to the file. 

You Type: (CLEAR)7W* 

Screen Shows: E:(A)W* 
LINE ONE 
SECOND LINE OF TEXT 
THIRD LINE OF TEX 
FOURTH LINE 
FIFTH LINE 
LAST LINE 


END OF TEATS 


Close the file. 
You Type: .«write// (ENTER 
Screen Shows: E:,-WRITE// 


Verify that the buffer is empty. 
You Type: (CLEAR)7L* (ENTER 
Screen Shows: E:(4)L+* 


Si 


Open the file ‘‘oldfile’’ for reading. 
You Type: »-READ"oldfile” (ENTER 
Screen Shows: E:-READ"oldfile" 


Create a new file called ‘‘newfile’’ for writing. 
You Type: »-WRITE"newfile" (ENTER 
Screen Shows: E: -WRITE"newfile" 


Read four lines from the input file. The screen shows the lines as 
they are read in. 
You Type: Rk4 
Screen Shows: E:k4 
LINE ONE 
SECOND LINE OF TEAT 
THARD LINE OF TRAT 
FOURTH LINE 


Read all the remaining text from the file. The screen shows the 
lines. When there is no more text, the screen shows the 
*END OF FILE* message. 
You Type: R* 
Screen Shows: E:k* 
LINE FIVE 
LAST LINE 


ZENG UP FLL 


Go to the top of the buffer and display the text to make sure that 
it was inserted into the buffer. 
You Type: (CLEAR)7.* (ENTER) 
Screen Shows: E :(C4)L* 
LINE ONE 
SECUND LINE OF TEXT 
THIRD LINE OP TERT 
FOURTH LINE 
PIFTH tine 
LAST LINE 


Write three lines to the output file and display the lines. 
You Type: W3 
Screen Shows: E:W3 
LINE ONE 
BEGUN LINE UP. TEAT 
THIRD LIN: OF TEXT 
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Move to the next line and display it. 
You Type: + 
Screen Shows: E: + 
FIFTH LING 


Show that the lines are written starting at the current line and not 
at the top of the buffer. 
You Type: 
Screen Shows: E: 
PIFip iia 


Go to the top of the buffer and display the text to make sure that 
the lines were written to the output file. 
You Type: (CLEAR)7L* (ENTER) 
Screen Shows: —:C4)L¥* 
FOURTH LINE 
LAST LINE 


Clear the buffer. 
You Type: (CLEAR)7D* (ENTER) 
Screen Shows: £:(4)D# 
FOURTH LINE 
LAST LINE 


Switch to Buffer 2. Open the input file ‘‘oldfile’’ and read two 
lines from it. 
You Type: BZ +READ"oldfile" Rez (ENTER 
Screen Shows: E:82 .READ"oldfile" Re 
LINE ONE 
SECOND LINE OF TEXT 


Switch to Buffer 1. Open the input file ‘‘oldfile’’ and read one 
line of text. 
You Type: B -READ"oldfile" R (ENTER 
Screen Shows: E:8 +»READ"“oldfile" k& 
LINE ONE 


Switch to Buffer 2 and read one line. Note: Your place in the file 
was not lost. 
You Type: BZ F (ENTER 


Screen Shows: E: Be RF 
THIRD LINE OF TEXT 


Switch to Buffer 1 and read one line of text. Note: Your place in 


the file was not lost. 


You Type: B F (CENTER 
yp 53 


Screen Shows: E:B R 
SECOND LINE OF TEXT 


Switch to Buffer 2 and delete its contents. 
You Type: B2 (CLEAR)7D* (ENTER) 
Screen Shows: E:B2 (4)D* 
LINE ONE 
SECOND LINE OF TEXT 
THIRD LINE OF TEXT 


Insert some extra lines into the buffer. 
You Type: (SPACEBAREXTRA LINE ONE 
(SPACEBAREXTRA LINE TWO 
Screen Shows: E: EXTRA LINE ONE 
E: EXTRA LINE TWO 


Try to write B2 buffer to file. It fails because a file has not been 
opened in this buffer. 
You Type: (CLEAR)7 Wi * 
Screen Shows: E:(4)W* 
#FILE CLOSED 


Close the file for Buffer 1 and return to Buffer 2. 
You Type: B .WRITE// Baz (ENTER 
Screen Shows: E:8 .WRITE// Bo 


Open the old ‘“‘write’’ file for reading and then read it back in. 
You Type: -READ"newfile" R* 
Screen Shows: E:.READ"newfile" R* 

LINE ONE 

SECOND LINE OF TEXT 
THIRD LINE QE TEXT 
FIFTH LINE 


PEND UP FILES 


Display the contents of the buffer. Note: It read the file into the 
beginning of the buffer, since that was the position of the edit 
pointer. 
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You Type: (CLEAR)7.* (ENTER) 

Screen Shows: E:(4)L¥* 
LINE ONE 
SECOND LINE OF TEXT 
THIRD LINE OF TEXT 
PIFTH LINE 
EXTRA LINE ONE 
EXTRA LINE TWO 


Sample Session 5 


Delete all text from the edit buffer. 


You Type: (CLEAR)7D* (ENTER 
Screen Shows: E:(4)D* 


Insert three lines. 

You Type: (SPACEBAR)L INE ONE 
(SPACEBAR)LINE TWO 
(SPACEBAR)LINE THREE 

Screen Shows: E: LINE ONE 

LING THO 
LINE THREE 


Create a new macro using an empty string. 


You Type: .MAC// (ENTER 
Screen Shows: E:.MAC// 


Display the contents of the macro mode, which is now open. 
Note: The E prompt is now M. 

You Type: (CLEAR)7L* (ENTER) 

Screen Shows: M:C4)L* 


Define the macro. 
You Type: (SPACEBAR)F IND 
(SPACEBAR)S "TWO" (ENTER 
Screen Shows: M: FIND 
=e 


a3 


56 


Display the contents of the macro. 
You Type: (CLEAR)7.* (ENTER) 
Screen Shows: M:(C4)L* 

FIND 
Ss" TWO" 


Close the macro’s definition. 


You Type: 9 (ENTER 


Screen Shows: E: 


Display the directory of buffers and macros. 
You Type: .DIR (ENTER 
Screen Shows: E:.DIR 
GUPPFERS 


$ "4 

* 1 

MACROS: 
FIND 


Display the contents of the edit buffer. 
You Type: (CLEAR)7L + 
Screen Shows: E:(4) L* 

LINE ONE 
LINE THO 
LINE THREE 


Use the FIND macro to find the string ‘‘TWO.”’ 
You Type: .FIND 
Screen Shows: E:.FIND 
LINE TWO 


Reopen the definition of the FIND macro. 


You Type: .MAC/FIND/ (CENTER 
Screen Shows: E:.MAC/FIND/ 


Show that the macro is still intact. 
You Type: (CLEAR)7.* (ENTER) 
Screen Shows: M:(4)L+# 

FIND 
s"TWO" 


S9@eeeeeeeeeeeeeeeeeeeeeeeeeeeeeee ee @ eC 
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Add the numberic parameter and the string parameter to the 
macro’s header. 
You Type: C/FIND/FIND #N $5TR/ 
Screen Shows: M:C/FIND/FIND #N $STR/ 
FIND #N #5TR 


Move to the second line of the macro. 
You Type: + 
Screen Shows: M: + 
vo aaa ag 


Give the macro’s parameters to the S command. Now the FIND 
macro will perform the same function as the S command. 
You Type: C/"THO"/ #N $STR/ (ENTER 
Screen Shows: M:C/"TWO"/ #N $5TR 
5S #N $STR 


Close the macro’s definition. 
You Type: 9 (ENTER 


Screen Shows: E: 


Display the contents of the edit buffer. 
You Type: (CLEAR)7L.* (ENTER) 
Screen Shows: E:(4)L* 

LINE ONE 
LINE TWO 
LINE THREE 


Use the FIND macro to find the next two occurrences of 
“LINE”? 
You Type: -FIND 2 /LINE/ 
Screen Shows: E:.FIND 2 /LINE/ 
LINE ONE 
LINE TWO 


Create a new macro. 
You Type: ».MAC// (ENTER 
Screen Shows: E:.MAC// 
ts 
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Define the macro ‘‘FIND— LINE,’’ which performs the same 
function as the S command except that it returns the edit pointer 
to the head of the line after the last occurrence of ‘“‘STR’’ is 
found. 
You Type: (SPACEBAR)F IND_LINE #N $STR 
Screen Shows: M: FIND LINE #N $5TR 


You Type: (SPACEBAR)S #N $STR (ENTER 
Screen Shows: M: S #N STR 


Turn off the verify mode. 
You Type: (SPACEBAR)')@ (ENTER 


Screen Shows: M: W@ 


Move the edit pointer to the first character of the current line. 
You Type: (SPACEBAR) -@ (ENTER 


Screen Shows: M: -@ 


Close the macro’s definition. 
You Type: 9 (ENTER 
Screen Shows: /:9 

es 


Display the contents of the edit buffer. 
You Type: (CLEAR)7L * 
Screen Shows: E:(4)L¥ 

LINE ONE 
LINE TWO 
LINE THREE 


Use the ‘“‘FIND—LINE”’ macro to search for the string 
at W'S ae 
You Type: »«FINDULINE/TWO/ 
Screen Shows: E:.FINDULINE/TWO/ 
LINE TWO 


Show that the ‘‘FIND—LINE’”’ macro left the edit pointer at the 
head of the line. 
You Type: L 
Screen Shows: E:L 
LINE THO 
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Create a new macro. 
You Type: .MAC// (ENTER 
Screen Shows: E:+MAC// 


ye 


Use the exclamation point (!) command to comment itself. Type 
the following: 


CONVERTUTO_LLINES #N 

| This 15 a comment 

| 

| This macro converts 
the next n 


| space characters to new line 
| characters. 
Wo [| Turn verify mode 
off 
| to Prevent inter- 
mediate results 
! from being 
displayed, 
| 
[ | Begin looper 
»>SEARCH/ / ! Search for isPace? 


character, 
Ls 7 | Insert empty 
line (new line 
character). 
7 | Back up one line. 
Ce OFF | Delete the 
next sPace 
character, 


oe | Show Lline+ move 
Past it, 
] #N | End of loore, 


Repeat #N times, 


Close the macro’s definition. 
You Type: © (ENTER 


Screen Shows: Mi: 9 


rae 
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Display the contents of the edit buffer. 
You Type: (CLEAR)7L * 
Screen Shows: E:(4)L¥ 

LINE ONE 
LINE TWO 
LINE THREE 


Convert all space characters to new line characters. Note: The 
loop stops when the C command in the macro cannot find a 
space to delete. 
You Type: .CONVERTLTO_LLINES * 
Screen Shows: E: -CONVERTUTO_LINES * 
LINE 
LINE 
LINE 


Display the contents of the edit buffer. 
You Type: (CLEAR)? * 
Screen Shows: E:(4)L+# 

LINE 
ONE 
LINE 
TWO 
LINE 
THREE 
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Appendices 


Appendix A / Glossary 


BUFFER 


EDIT POINTER 


MACRO 


PATHLIST 


PSEUDO MACRO 


TEAT FILE 


WORKSPACE 


EDIT 


EDIT newfile 
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Holding area in memory for text. 


Internal marker the editor uses to 
remember your position in the edit 
buffer. 


New command you may define; it is 
composed of existing commands. Use 
macros to repeat the same command 
sequence over and over again. 


See the OS-9 Commands. 


Command that is part of the EDIT pro- 
gram and written in assembly language 
that is used as if it were a macro. 


Place where OS-9 keeps the text that 
you want saved. 


Available memory pool that the editor 
uses for buffers and macros. 


Appendix B / Quick Reference Summary 


OS-9 loads the editor and starts it. 
There are no initial read or write files. 
Perform text-file operations by opening 
files after the editor is running. 


If newfile does not exist, OS-9 loads the 
editor and starts it. The editor creates a 
file called newfile, and this is the initial 
write file. There is no initial read file; 
however, files may be read if they are 
opened. after the editor is started. 
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Edit Commands 
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EDIT oldfile 


EDIT oldfile newfile 


.MACRO 


— 


SPACEBAR 


ENTER 


OS-9 loads the editor and starts it. The 
initial read file is oldfile. The editor 
creates a new file called SCRATCH; 
this is the initial write file. When the 
edit session is complete, o/dfile is de- 
leted, and SCRATCH is given the 
name oldfile. 


OS-9 loads the editor and starts it. The 
initial read file is oldfile. The editor 
creates a file called newfile, and this is 
the initial write file. 


Executes the macro specified by the 
name following the period (.). 


Places comments inside a macro and 
ignores the remainder of the command 
line. 


Inserts line before the current position 
of the edit pointer. 


Moves the edit pointer to the next line 
and displays it. 


Moves the edit pointer forward n lines 
and displays the line. 


Moves the edit pointer backward n lines 
and displays the line. 


Moves the edit pointer to the last char- 
acter of the line. 


Moves the edit pointer to the first char- 
acter of the current line and displays it. 


Moves the edit pointer forward n 
characters. 
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CLEAR)7 


[commands] n 


AO 


Bn 


Cn strl str2 


Dn 


En str 


Gn 


In str 


Moves the edit pointer backward n 
characters. 


Moves the edit pointer to the beginning 
of the text. 


Moves the edit pointer to the end of the 
text. 


Repeats the sequence of commands be- 
tween the two brackets n times. 


Skips to the end of the innermost loop 
or macro if the fail flag is not on. 


Sets the SEARCH/CHANGE anchor to 
Column n, restricting searches and 
changes to those strings starting in the 
Column n. This command remains in 
effect for the current command line. 


Returns the anchor to the normal mode 
of searching so that strings are found 
regardless of the column in which they 
Start. 


Makes buffer n the primary buffer. 


Changes the next n occurrences of 
string] to string2. 


Deletes n lines. 


Extends (adds the string to the end of) 
the next n lines. 


Gets n lines from the secondary buffer, 
starting from the top. Inserts the lines 
before the current position in the prim- 
ary buffer. 


Inserts a line containing n copies of the 
string before the current position of the 
edit pointer. 
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Pn 


Rn 


Sn str 


Vmode 


Kills n characters starting at the current 
position of the edit pointer. 


Lists (displays) the next n lines, starting 
at the current position of the edit 
pointer. 


Changes workspace (memory) size ton 
bytes. 


Puts (moves) n lines from the position 
of the edit pointer in the primary buffer 
te the position of the edit pointer in the 
secondary buffer. 


Quits editing (and terminates editor). If 
you specified file(s) when you entered 
EDIT, Buffer 1 is written out to the 
output file. The remainder of the input 
file is copied to the output file. All files 
are closed. 


Reads n lines from the buffer’s input 
file. 


Searches for the next n occurrences of 
the string. 


Tabs to Column n of the present line. If 
nis greater than the line length, the line 
is extended with space. 


Unextends (truncates) line at the cur- 
rent position of the edit pointer. 


Turns the verify mode on or off. 


Writes n lines to the buffer’s output 
file. 


Displays n lines that precede the edit 
position. The current line is counted as 
the first line. 
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Pseudo Macros 


-CHANGE 


n strl str2 


.DEL str 


.DIR 


.EOB 


.ZOF 


-LOAD str 


.MAC str 


.NEOB 


.NEOL 


.NEW 


.NSTR str 


-READ str 


Changes n occurrences of str/ to str2. 


Deletes the macro specified by string. 


Displays the directory of buffers and 
macros. 


Tests for the end of the buffer. 
Tests for the end of the file. 
Tests for the end of the line. 


Exits the innermost loop or macro and 
sets the fail flag. 


Loads macros from the path specified 
in the string. 


Opens the macro specified by the string 
for definition. If an empty string is 
given, a new macro is created. 


Tests for not end of buffer. 
Tests for not end of file. 


Writes lines out to the initial output file 
up to the current line and then attempts 
to read an equal amount of text from the 
initial input file. The test read-in is 
appended to the end of the edit buffer. 


Tests to see if string does not match the 
characters at the current position of the 
edit pointer. 


Opens an OS-9 text file for reading, 
using string as the pathlist. 


Exits the innermost loop or macro and 
succeeds (clears the fail flag). 
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SEARCH n str 


SAVE strl str2 


SHELE, 
command line 


/SIZE 


STAR n 


STR str 


.WRITE str 


.LERO n 


[ 
| 


C4) 
type (CLEAR)7. 


Searches for n occurrences at str. 


Saves the macros specified in string] 
on the file specified by the pathlist in 
string2. 


Calls OS-9 shell to execute the com- 
mand line. 


Displays the size of memory used and 
the amount of memory available in the 
workspace. 


Tests to see if n equals asterisk 
(infinity). 


Tests to see if string matches the char- 
acters at the current position of the edit 
pointer. 


Opens an OS-9 text for writing, using 
string as a pathlist. 


Tests n to see if it is zero. 
Starts at a macro loop; type (CLEAR)8. 
Ends at a macro loop; TYPE (€LEAR)9. 


Moves edit pointer to beginning of 
buffer; 


Appendix C / Editor Error Messages 
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BAD MACRO 
NAME 


BAD NUMBER 


The first line in the macro does not 
begin with a legal name. You can close 
the definition of a macro after you give 
it a legal name. 


You have entered an illegal numeric 
parameter, probably a number greater 
than 65,535. 
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BAD VAR NAME 


BRACKET 
MISMATCH 


BREAK 


DUPL MACRO 


END OF FILE 


FILE CLOSED 


MACRO IS OPEN 


MISSING DELIM 


NOT FOUND 


UNDEFINED VAR 
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You have specified an illegal variable 
name. Usually, you omitted the vari- 
able name or inadvertently included a 
$ or # character in the commands 
parameter list. 


You have not entered brackets in pairs 
or the brackets are nested too deeply. 


You typed (CONTROL)CC ) = or 
(CONTROL)( Q_) to interrupt the editor. 
After printing the error message, the 
editor returns to command entry mode. 
Note: Results may not be displayed 
during command operation. 


You attempted to close a macro defini- 
tion with the same name as another 
macro. Rename the macro before 
trying to close its definition. 


You are at the end of the edit buffer. 


You tried to write to a file that was 
never opened. Either specify a write 
file when starting the editor from OS-9, 
or open an output file using the 
.WRITE pseudo macro. 


Close the macro definition before using 
the command that caused this error. 


The editor could not find a matching 
delimiter to complete the string you 
specified. You must put the string com- 
pletely on one line. 


The editor cannot find the specified 
string or macro. 


You used a variable that was not speci- 
fied in the macro’s definition parameter 
list. A variable parameter may be used 
only in the macro in which it is 
declared. 
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WHAT ?? 


WORKSPACE FULL 


The editor did not understand a com- 
mand you typed. This is usually caused 
by entering a command that does not 
exist (misspelling its name). 


The buffer did not have room for the 
text you attempted to insert. Increase 
the workspace or remove some text. 
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OS-9 Assembler 
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1 / Introduction 


Installation 


The machine instructions executed by a computer are se- 
quences of binary numbers that are difficult for people to deal 
with directly. Creating a machine-language program by hand 
is tedious, error prone, and time consuming. Assembly lan- 
guage bridges the gap between computers and machine- 
language programmers. 


Assembly language uses descriptive mnemonics (abbrevia- 
tions) for each machine instruction instead of numerical 
codes. These are much easier to learn, read, and renumber. 
The assembler also lets the programmer assign symbolic 
names to memory addresses and constant values. 


This assembler is designed expressly for the modular, multi- 
tasking environment of the OS-9 Operating System and in- 
corporates built-in functions for calling OS-9, generating 
memory modules, encouraging the creation of position- 
independent-code, and maintaining separate program and data 
sections. It is also optimized for use by OS-9 high-level lan- 
guage compilers such as Pascal and C. 


The OS-9 assembler is extremely fast as a result of its tree- 
structured symbol table organization. This dramatically re- 
duces the time for symbol table searching. 


This manual describes how to use the OS-9 Assembler and 
explains basic programming techniques for the OS-9 environ- 
ment. It is not a comprehensive course on assembly language 
programming or the 6809 instruction set. 


If you are not familiar with these topics, consult the Motorola 
6809 programming manuals and one of the many excellent 
assembly-language programming books available at libraries 
and bookstores. 


The OS-9 Assembler distribution disk contains the asm file 
(the assembler program) and the DEFS file (a directory con- 
taining OS-9 common system-wide definition files; see chap- 
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ter 7). These files are OS9Defs, SysType, SCFDefs, and 
RSFDefs. 


Copy the asm file to the CMDS directory of your system 
disk. Create a directory on your system disk called DEFS (if 
not already present) and copy the four DEFS files to it. Place 
the assembler distribution disk in Drive 1 and your system 
disk in Drive 0. Use the following commands. 


copy/d1/asm/d0/cmds/asm #12k 

makdir /dO/DEFS 

copy /d1/defs/os9defs /dO/defs/os9defs #12k 
copy /d1/defs/systype /dO/defs/systype #12k 
copy /d1/defs/scfdefs /dO/defs/scfdefs #12k 
copy /d1/defs/rbfdefs /dO/defs/rbfdefs #12k 


Assembly Language Program Development 


dz 


Writing and testing assembly language programs involves a 
basic edit-assemble-test cycle. 


1. Create a source program file using the text editor. 


2. Run the assembler to translate the source file to a 
machine-language file. 


3. If the assembler reports errors, use the text editor to cor- 
rect the source file. Go back to step 2. 


4. Run and test the program, using the OS-9 Interactive 
Debugger. 


5. If the program has bugs, use the text editor to correct the 
source file. Go back to step 2. 


6. Document the program. 
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Assembler Input Files 


The OS-9 Assembler reads from an input file (path) that con- 
tains variable-length lines of ASCII characters. You can cor- 
rect and edit input files with the OS-9 Macro Text Editor or 
with any other standard text editor. 


The maximum length of the input line is 120 characters. Each 
line contains assembler statements as explained in this man- 
ual. Terminate every line by typing (ENTER). 


Running the Assembler 


The assembler is a command program that can be run from 
the OS-9 Shell, from a shell procedure file, or from another 
program. The disk file and memory module names are ASM. 
The following is the basic format of a command line to run 
the assembler: 


asm file name [option(s)| [#memsize] [ >listing ] 


Brackets enclose options; therefore, the only required items 
are the ASM command name and the file name, which is the 
source text file name (pathlist). The following is a typical 
command: 


asm progs Is -c #12k >/p 


In this example the source program is read from the file 
PROGS. The source file name can be followed by an option 
list, which allows you to control various factors such as 
whether or not to generate a listing or an object file. 


The option list consists of one or more abbreviations sepa- 
rated by spaces or commas. An option is turned on by its 
presence in the list; a minus followed by an option abbrevia- 
tion turns off the function. If an option is not expressly given, 
the assembler assumes a default condition for it. 
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You can override command options by OPT statements with- 
in the source program. In the example above, the options 1 
and s are turned on, and c is turned off. 


The shell processes the optional #memsize item to specify 
how much data area memory the assembler is assigned. If this 
is not specified, the assembler is assigned 4K bytes of mem- 
ory in its data area. Most of this space is used to store the 
symbol table. Any additional memory that this option re- 
quests enlarges the symbol table. 


Large programs generally use more symbols; therefore, their 
memory requirements are correspondingly greater. If the 
assembler generates the ‘‘Symbol Table Full’’ error message, 
increase the assembler’s memory size. In the previous exam- 
ple, 12K bytes of memory are specified. 


The final item, “‘>listing’’, allows the program listing gener- 
ated by the assembler (on the standard output path) to be 
optionally redirected to another pathlist, which may be an 
output device such as a printer, a disk file, or a pipe to 
another program. 


The shell handles the memory size option, and it handles out- 
put redirection, not the assembler. If you omit this item from 
the command line, your screen shows the output. In the 
above example, the listing output is directed to device p, the 
printer on most OS-9 systems. 


Operating Modes 
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The OS-9 Assembler has a number of features specifically 
designed to conveniently develop machine-language programs 
for the OS-9 environment. These include special assembler 
directive statements for generating OS-9 memory modules, 
identification of 6809 addressing modes that are not usually 
permitted in OS-9 programs, and separate data and program 
address counters. 


The assembler has two operating modes — normal and 
Motorola-compatible. In normal mode, the features men- 
tioned above are active. In the Motorola-compatible mode, 
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the assembler works the same way as a standard 6809 *‘abso- 
lute’? assembler (without separate program and data count- 
ers). This mode exists so that you can use the assembler to 
generate programs for 6809 computers that are not equipped 
with OS-9. 


The assembler is in the normal mode unless you use the m 
option in the command line or in an OPT statement. 
The -m option returns the assembler to the normal mode (you 
can switch modes freely to achieve special effects). 


The assembler performs two ‘“‘passes’’ (complete scans) over 
the source file. During each pass, it reads input lines and 
processes them one at a time. During the first pass, it creates 
the symbol table. It generates most error messages, the pro- 
gram listing, and the object code during the second pass. 
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2 / Source Statement Fields 


Label Field 


Each input line is a text string that you terminate by typing 
(ENTER). The line can have from one to four fields — a label 
field, an operation field, an operand field (for some opera- 
tions), and a comment field. 


If you type an asterisk as the first character of a line, the 
assembler treats the entire line as a comment. It displays it in 
the listing but does not otherwise process it. The assembler 
ignores blank lines but includes them in the listing. 


The label field begins in the first character position of the 
line. Some statements require labels (for example, EQU and 
SET); others (assembler directives such as SPC, TTL) must 
not have them. The first character of the line must be a space 
if the line does not contain a label. 


The label must be a legal symbolic name consisting of from 
one to eight upper- or lower-case characters, decimal digits, 
or the characters dollar sign ($), underline (_), or dot (.); 
however, the first character must be a letter. You must not 
define labels (and names in general) more than once in a 
program (except when used with the SET directive). 


The symbol table stores label names with an associated 16-bit 
value, which is normally the program counter address before 
code is generated for the line. In other words, instructions 
and most constant-definition statements associate the label 
name with the value of the program address of the first object 
code byte generated for the line. 


An exception to this rule is that labels on SET and EQU 
statements are given the value of the result of evaluation of 
the operand field. In other words, these statements allow any 
value to be associated with a symbolic name. 


Likewise, labels on RMB statements are given the value of 
the data address counter when in normal assembler mode, or 
the value of the program address counter when in Motorola- 
compatible mode. 
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Operation Field 


Operand Field 


This field specifies the machine-language instruction or 
assembler directive statement mnemonic name. It immediate- 
ly follows and is separated from the label field by one or 
more spaces. 


Some instructions must include a register name that is part of 
the operation field (for example, LDA, LDD, LDU). In these 
instructions the register name must be part of the name and 
cannot be separated by spaces as in older 6800-type assem- 
blers. The assembler accepts instruction mnemonic names in 
either upper- or lower-case characters. 


Instructions generate one to five bytes of object code, de- 
pending on the specific instruction and addressing mode. 
Some assembler directive statements (such as FCB, FCC) 
also generate object code. 


The operand field follows and must be separated by at least 
one space from the operation field. Some instructions do not 
use an operand field; other instructions and assembler direc- 
tives require one to specify an addressing mode, operand, 
address, parameters, and so on. 


Comment Field 
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The comment field is the last field of the source statement 
and is used to include a descriptive comment. It is optional. 
The assembler does not process this field but copies it to the 
program listing. 
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3 / Symbolic Names and 
Expressions 


Evaluation of Expressions 


Operands of many instructions and assembler directives in- 
clude numeric expressions in one or more places. The 
assembler can evaluate expressions of almost any complexity, 
using a form similar to the algebraic notation in programming 
languages such as BASIC and FORTRAN. 


Expressions consist of operands, which are symbolic names 
or constants, and operators, which specify an arithmetic or 
logical function. All assembler arithmetic uses two-byte (in- 
ternally, 16-bit binary) signed or unsigned integers in the 
range of 0 to 65535 for unsigned numbers and — 32768 to 
+ 32767 for signed numbers. 


In some cases, expressions are expected to evaluate to a value 
that must fit in one byte (such as 8-bit register instructions) 
and therefore must be in the range of 0 to 255 for unsigned 
values and — 128 to 127 for signed values. In these cases, if 
the result of an expression is outside this range, the screen 
shows an error message. 


The assembler evaluates expressions from left to right, using 
the algebraic order of operations (that is, it multiplies and 
divides before it adds and subtracts). Parentheses alter the 
natural order of evaluation. 


Expression Operands 


You may use the following items as operands within an 
expression. 


Decimal Numbers. Optional minus sign (— ) and one to five 
digits. Examples: 


100 
32/07 

0 

12 
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Hexadecimal Numbers. Dollar sign ($) followed by one to 
four hexadecimal characters (0-9, A-F, or a-f). Examples: 


$ECOO 
$1000 
$3 
$0300 


Binary Numbers. Percent sign (%) followed by one to six- 
teen binary digits (0 to 1). Examples: 


%0101 
%1111000011110000 
% 10101010 


Character Constants. Single quote (’) followed by any 
printable ASCII character. Examples: 

"xX 

Cc 

see 
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Symbolic Names. One to eight characters, upper- and lower- 
case alpha (A-Z or a-z), digits (0-9), and special characters 
—, ., or $ (underscore, period, or dollar sign). The first char- 
acter cannot be a digit. 


Instruction Counter. Placed at the beginning of the line, the 
asterisk (*) represents the program instruction counter value. 


Data Counter. Placed at the beginning of the line, the period 
(.) represents the data storage counter value. 


‘‘Operators’’ specify arithmetic or logical operations to be 
performed within an expression. The assembler executes 
operators in the following order: (1) —, negative numbers; 
(2) & and !, logical AND and OR; (3) * and / , multiplication 
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and division; (4) + and —, addition and subtraction. Oper- 
ators in a single expression having equal precedence, for ex- 
ample, + and —, are evaluated left to right. You can use 
parentheses, however, to override precedence. 


Assembler Operators by Order of Evaluation 


— negative logical NOT 
& logical AND ! logical OR 
* multiplication / division 

+ addition — subtraction 


Logical operations are performed bitwise; that is, the logical 
function is performed bit by bit on each bit of the operands. 


Division and multiplication functions assume unsigned oper- 
ands, but subtraction and addition work on signed (2’s com- 
plement) or. unsigned numbers. The screen shows an error 
message if you attempt to divide by zero or multiply by a 
factor that results in a product larger than 65, 536. 


Symbolic Names 


A symbolic name consists of from one to eight upper- or 
lower-case characters, decimal digits, or the dollar sign ($), 
the underline (_), or the dot (.); however, the first character 
must be a letter. The following are examples of legal symbol 
names: 


HERE 
there 
SPL030 
VX_GH 
abc.def 
Q1020.1 
LJI23a.x 
tsinteger 
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These are examples of illegal symbol names: 


2move (does not start with a letter) 

main.backup (has more than eight characters) 

Ib1# 123 (contains #, which is not a legal name 
character) 


You define a name the first time you use it as a label on an 
instruction or directive statement. You can define a name 
only once in the program (except SET labels). If you redefine 
a name (use as a label more than once), the screen shows an 
error message. You cannot use multiple forward references 
(that is, a definition using currently undefined names). 


The symbol table stores symbolic names with their associated 
type and value. This structure uses most of the assembler’s 
data memory space. Using the default memory size of 4K, 
the symbol table has room for approximately 200 names. 


You can use the shell’s optional memory size modifier to 
increase the assembler’s memory space. Each entry in the 
table requires 15 bytes; therefore, each additional 4K of 
memory adds space for about 273 additional names. 


For example, the command line 
asm sourcefile #16K 


gives the symbol table enough space for a little more than a 
thousand names. If you select the S option, the assembler 
generates an alphabetical display of all symbol names, types, 
and values at the end of the assembly. 
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4 / Instruction Addressing Modes 


The instruction set has a wide variety of addressing modes. 
Each group of similar instructions is used with specific 
addressing modes, which are usually specified in the assem- 
bler source statement operand field. The assembler generates 
an error message if an addressing mode is specified that can- 
not legally be used with the specific instruction. 


Inherent Addressing 


Certain instructions do not need operands (for example, 
SYNC and SWI); others implicitly specify operands (for ex- 
ample, MUL and ABX). In these cases no operand field is 
needed. 


Accumulator Addressing 


Some instructions have the A or B accumulators as operands. 
Examples: 


CLRA 
ASLB 
INCA 


Immediate Addressing 


In immediate addressing, the instruction uses the operand 
bytes as the actual value. Instructions that use 8-bit registers 
must have operand expressions that evaluate in the range of 0 
to 255 (unsigned) or — 128 to 127 (signed). If they do not, 
the screen shows an error message. 


The syntax is: 


instr #expression 
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Examples: 


LDD #$1F00 
Idb #bufsiz+2 
ORCC #S$FF-CBIT 


Relative Addressing 


Branch-type instructions, such as BCC, BEQ, LBNE, BSR, 
and LBSR, use the relative addressing mode. The operand 
field is an expression that is the ‘‘destination’’ of the instruc- 
tion, which is almost always a name used as a statement label 
somewhere in the program. 


The assembler computes an 8- or 16-bit program counter 
offset to the destination, which is made part of the instruc- 
tion. If the destination of short branch-type instructions is not 
in the range of —126 to +129 bytes of the instruction 
address, the screen shows the error message. 


Long branch-type instructions can reference any destination. 
If a long branch instruction references a destination that is 
within the range of a smaller and faster short branch instruc- 
tion, the assembler places a warning symbol (W) in the listing 
line’s information field. All instructions using relative address- 
ing are inherently position independent code. Examples: 


BCS LOOP 
LBNE LABELS 
LBSR START +3 
BLT COUNT 


Extended and Extended Indirect Addressing 
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Extended addressing uses the second and third bytes of the 
instruction as the absolute address of the operand. Data sec- 
tion addresses of OS-9 programs are assigned when the pro- 
gram is actually executed; therefore, absolute memory 
addresses are not known before the program is run, and this 


©9@0e0e00e0808eeeeeeeeeeeeeeeeeeeeeeeeeee@ @ é 


ZSEREEeeeeeeeeeeeyeyeyYyeeeeeeeeeeuEeeRey 


addressing mode is not normally used in OS-9 programs. The 
screen shows an informational warning flag (W) if this 
addressing mode is specified. 


Extended indirect addressing is similar to extended addressing 
except that the address part of the machine instruction is used 
as the address of a memory location containing the address of 
the operand. 


Because this mode also uses absolute addresses, it is not fre- 
quently used in OS-9, and the assembler flags it with a warn- 
ing. Select this addressing mode by enclosing the address 
expression in brackets. Examples: 


ADDA $1C48 extended addressing 
ADDA [SD58A] extended indirect addressing 
LBD START — extended addressing 
stb [end] extended indirect addressing 


Direct Addressing 


Direct addressing uses the second byte of the instruction as 
the least significant byte of the operand’s address. The most 
significant byte is obtained from the MPU’s direct page 
register. 


This addressing mode is preferred for accessing most vari- 
ables in OS-9 programs because OS-9 automatically assigns 
unique direct pages to each task at run time and because this 
mode produces short, fast instructions. 


The syntax for extended and direct addressing has the same 
form: 


instr <addr expr> 


The assembler automatically selects direct addressing mode if 
the high-order byte of the address matches its internal *‘direct 
page.’’ This direct page is not the same as the run-time direct 
page register; it is an assembly-time value. You ordinarily set 
it to zero, but you can change it with the SETDP directive. 
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You can force the assembler to use direct addressing by typ- 
ing the less than symbol (<) just before the address expres- 
sion or to use extended addressing by typing the greater than 
symbol (>) just before the address expression. Examples: 


Ida temp (assembler selects mode) 
LDD >PAI+1 (forces extended addressing) 
Idx <count (forces direct addressing) 


STD _ [pointer] (extended indirect) 


Register Addressing 
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Some instructions operate on various MPU registers, which 
are referred to by a one- or two-letter name. In these instruc- 
tions the operand field specifies one or more register names. 
The names, which can be upper- or lower-case, are: 


A accumulator A (8 bits) 
B accumulator B (8 bits) 
D accumulator A:B concatenated (16 bits) 
DP direct page register (8 bits) 
& © condition codes register (8 bits) 
X index register X (16 bits) 
a index register Y (16 bits) 
stack pointer register (16 bits) 
U user stack pointer register (16 bits) 
PC program counter register (16 bits) 


The EXG and TFR instructions have the form: 
instr reg,reg 


If the registers are not the same size (either 8 or 16 bits), the 
screen shows the error message. 


The PSHS, PSHU, PULS, and PULU instructions accept a 
list of one or more register names. Even though the assembler 
accepts register names in any order, the MPU stacks and un- 
stacks them in a specific order. 
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The syntax for these instructions is: 
instr regi,reg} 
Examples: 


TFR X<Y 
EXG A,DP 
pshs a,b,x,dp 
PUBL “dix.pe 


Indexed Addressing 


The 6809 has 23 varieties of indexed addressing modes. In- 
dexed addressing is analogous to “‘register indirect,’’ mean- 
ing that an indexable register (X, Y, U, S, or PC) is used as 


the basic address of the instruction’s operand. 


The different varieties of indexed addressing use the specified 
register contents, which may be unchanged, temporarily mod- 
ified, or permanently modified, depending on the mode. 


All indexed modes must specify an index register, either X, 
Y, U, or SP. You can use the Register PC with the program- 
counter relative mode only. 


To make any indexed addressing mode “‘indirect,’’ enclose 
the operand field in brackets. The effective address generated 
by the addressing mode is used as the address of a pointer to 
the operand rather than as the address of the operand. 


Constant Offset Indexed 


This mode uses an optional signed (two’s complement) offset 
that is temporarily added to the register’s value to form the 
operand’s effective address. The offset can be any number; if 
it is zero, the register’s unaltered content is used as the effec- 
tive address. The assembler automatically picks the shortest 
of four possible varieties that can represent the offset. 
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If a symbolic name used in the offset expression is not de- 
fined, the assembler generates longer code than necessary or 
produces phasing errors. 


The syntax for constant offset indexed instructions is: 


instr reg zero offset 

instr offset,reg constant offset 

instr [ reg] zero offset indirect 

instr [offset.reg | constant-offset indirect 
Examples: 

lda Xx no offset 

Ida Ox no offset 

Idx 100, x offset of 100 

LDB COUNT,S offset of COUNT 

Idd temp + 2,y offset of temp + 2 

leax a offset of —2 

clr [PIA,X] indirect mode 


Program Counter Relative Indexed 
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This addressing mode is similar to constant-offset indexed ex- 
cept that the program counter register (PC or PCR) is used as 
an index register, and the assembler computes the offset dif- 
ferently. Instead of using the offset expression directly, the 
expression is assumed to refer to the address of the operand. 


The assembler calculates the required offset from the current 
program counter location to the operand’s address and uses 
the resulting value as the offset. One form of this instruction 
uses an 8-bit offset and the other uses a 16-bit offset. The 
assembler uses the 16-bit form unless you force the short 
form by typing the less than symbol (<) before the operand 
field. 


The syntax for program-counter relative indexed is: 


instr addr,PC program counter relative 
instr addr,PCR program counter relative 
instr [addr,PCR] program counter relative indirect 
instr [addr,PC] program counter relative indirect 
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This addressing mode permits addresses of constants and con- 
stant tables to be accessed using position independent code as 
required by OS-9. 


Examples: 


Idd =‘ temp,per 


LDD temp,pc same as instruction above 
leax _ table,pcr 
jsr addr ,pcr same as ‘“‘Ibsr addr’’ 


CLR [control+4,PCR] dangerous; uses absolute 
address at ‘“‘control +4,PCR”’ 
as effective address for clear 


Accumulator Offset Indexed 


In this mode the contents of the A, B, or D accumulators are 
temporarily added to the specified index register to form 
the address of the operand. This addition is signed two’s 
complement. 


If you specify the A or B accumulators, the sign bit is ‘‘ex- 
tended’’ to form the 16-bit value, which is added to the index 
register. This means that if the most significant bit of the 
accumulator is set, the high order byte of the offset is SFF. 


Beware: This is a commonly overlooked characteristic that 
can produce unexpected results! Using the D register avoids 
this because it gives all 16 bits. 


The syntax for accumulator-offset indexed is: 


instr A,reg 
instr B,reg 
instr D,reg 


Examples: 


LDX B,Y 
LEAY D,X 
ROL [B,U] 
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Auto-Increment and Auto-Decrement Indexed 
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These addressing modes use the specified index register as 
the effective address of the operand while permanently adding 
or subtracting one or two from the register. In auto-increment 
mode, the increment is performed after the register is used. In 
auto-decrement mode, the decrement is performed before the 
register is used. This is consistent with the way 6809 stack 
pointers operate in PSH and PUL instructions. 


If you use indirect addressing, the decrement and increment 
are performed before the effective address is used as a pointer 
to the operand. You cannot use single auto-increment and 
single auto-decrement when you select indirect addressing. 


Syntax for auto-increment and auto-decrement indexed 
addressing is: 


instr {Tes single auto-decrement 

instr so =Teg double auto-decrement 

instr eg + single auto-increment 

instr tes > double auto-increment 

instr [,reg——] double auto-decrement indirect 


instr [,reg+ +] double auto-increment indirect 


Examples: 
clr j,x++ 
LX =e 
Ida _ ,s+ is the same as puls a (except CCR is affected) 
sta ,—sis the same as pshs a (except CCR is affected) 
Idd [,s++] 
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5 / Pseudo Instructions 


Pseudo instructions are special assembler statements that 
generate object code but do not correspond to actual 6809 
machine instructions. Their primary purpose is to create spe- 
cial sequences of constant data to be included in the program. 
Labels are optional on pseudo instructions. 


FCB <expression> {, <expression>} 


generates sequences of single byte constants (FCB) within the 
program. The screen shows the error message if an expres- 
sion has a value of more than 255 or less than — 128 (the 
largest number that can be represented by a byte). 


FDB <expression> {, <expression>} 


FCB ‘A 
FDB ‘CN’ 
FCB ‘? +80 
FCC string 
FCS string 


generates sequences of double byte constants (FDB) within 
the program. If this statement evaluates an expression with an 
absolute value of less than 256, the high order-byte is zero. 


The operand is a list of one or more expressions that are 
evaluated and output as constants. To generate more than one 
constant, separate the expressions with commas. 


Examples: 
FCB 1,20,A 
fcb index/2 + 1,0,0,1 
FBD 1,10,100,1000, 10000 


fdb $F900,$FA00,$FB00,$FCOO 


generate a series of bytes corresponding to a specified string 
of one or more characters operand. 


91 


The output bytes are the literal numeric value of each ASCII 
character in the specified string. FCS is the same as FCC 
except the most significant bit (the sign bit) of the last charac- 
ter in the specified string is set. This is a common OS-9 
programming technique to indicate the end of a text string 
without using additional storage. 


You must enclose the characters in the specified string 
with delimiters. You can use the following characters as 
delimiters: | 


age ee oe ada ke oe 


The delimiters must be identical, and you cannot include 
them in the string itself. Examples: 


FCC /most programmers are strange people/ 
FCS 50123456789, 
fee $z$ 


MOD size,nameoff,typelang,attrrev {,execoff,memsize} 


92 


creates a standard OS-9 module header and initializes a CRC 
(cyclical redundancy check) value that the assembler auto- 
matically computes as it processes the program. 


OS-9 can load programs into memory only if they are in 
module header format. You use the MOD statement at the be- 
ginning of an OS-9 module. It must have an operand list of 
exactly four or exactly six expressions separated by commas. 
Each operand corresponds, in order, to the elements of a 
module header. The exact operation of the MOD statement is 
as follows: 


1. Resets the assembler’s program address counter and data 
address counters to zero (same as ORG QO) and initializes 
the internal CRC and vertical parity generators. 


2. Generates the sync codes $87 and $CD as object code. 
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EMOD 


3. Evaluates and outputs as object code the first four expres- 


sions in the operand list. They are: 


module size (two bytes) 

. module name offset (two bytes) 
. type-language byte (one byte) 

. attribute-revision byte (one byte) 


ands & 


4. Computes the header parity byte from the previous bytes 
and generates it as object code. 


5. Evaluates the two optional additional operands if they are 
present and generates them as object code. They are: 


e. execution offset 
f. permanent storage size 


Note: Some expressions in the operand list are one byte long, 
and others are two bytes. 


Because the origin of the object program is zero, all labels 
used in the program are inherently relative to the beginning of 
the module. This is perfect for the module name and execu- 
tion address offsets. The code in the body of the module fol- 
lows. As subsequent lines are assembled, the internal CRC 
generator continuously updates the module’s CRC value. 


terminates the module. 


The EMOD statement has no operand. It outputs the correct 
three-byte CRC generated over the entire module. 


Note: The MOD and EMOD statements do not work correct- 
ly if the assembler is in Motorola-compatible mode unless 
you do not use RMB or ORG statements after the MOD and 
before the EMOD. 


The example below illustrates the basic techniques of creating 
a module using MOD and EMOD statements. 


type set PRGRM+OBJCT (these are defined in 
OS9DEFS) 
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OS9 <expression> 
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revs set REENT + 1 (this is defined in 
OS9DEFS) 
MOD pgmlen,name,type,revs,start,memsize 


* data storage declarations 


temp RMB 1 
addr RMB 2 
buffer RMB 500 
stack RMB 250 


memsiz EQU data storage size is final ‘‘.’’ value 
name FCS /textmodule/ 
start leax buffer,u get address of buffer 
clr temp 
inc temp 
Idd #500 loop count 
loop clr .X+ 
subd #1 
bne loop 
os9 F$EXIT return to OS9 
EMOD 


pgmlen EQU * program size is addr of last byte +1 


generates OS-9 system calls. 


This statement has an operand that is a byte value to be used 
as the request code. The output is equivalent to the instruction 
sequence: 


SW 12 
FCB operand 
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The OS9Defs file contains standard definitions of the sym- 
bolic names of all OS-9 service requests. You can use these 
names in conjunction with the OS9 statement to improve the 
readability, portability, and maintainability of assembly- 
language software. 


Examples: 
OS9 I$Read (call OS-9 READ service request) 


OS9 FS$Exit (call OS-9 EXIT service request) 
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6 / Assembler Directive Statements 


Assembler directive statements give the assembler infor- 
mation that affects the assembly process but that does not 
generate code. Read the descriptions carefully because some 
directives require labels, labels are optional on others, and a 
few cannot have labels. 


END 


indicates the end of a program. 


The use of this statement is optional since END is assumed 
upon an end-of-file condition on the source file. End state- 
ments may not have labels. 


label EQU <expression> 
label SET <expression> 


assign a value to a symbolic name (the label). 


The value assigned to the symbol is the value of the operand, 
which may be an expression, a name, or a constant. 
These statements require labels. 


Note: If you define symbols by EQU statements, you can 
define them only once in the program. If you define symbols 
by SET statements, you can redefine them by subsequent 
SET statements. 


In EQU statements the label name must not have been used 
previously, and the operand cannot include a name that has 
not yet been defined (that is, it cannot contain as-yet unde- 
fined names the definitions of which also use undefined 
names). 


In a good program all equates are at the beginning. This lets 
the assembler generate the most compact code by selecting 
direct addressing wherever possible. 
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IFxx <expression> 
<statements> 
[| ELSE | 
<statements> 
ENDC 
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You can use EQU to define program symbolic constants, 
especially those used in conjunction with instructions. You 
can use SET to define symbols that control the assembler 
operations, especially conditional assembly and listing con- 
trol. Examples: 


FIVE equ 5 
OFFSET equ address-base 
TRUE equ $FF 
FALSE equ 0 
SUBSET set TRUE 
ifne SUBSET 
use subset.defs 
else 
use full.defs 
endc 
SUBSET set FALSE 


The assembler has conditional assembly capability. It can 
selectively assemble or not assemble one or more parts of a 
program, depending on a variable or computed value. There- 
fore, a single source file can selectively generate multiple 
versions of a program. 


Conditional assembly uses statements similar to the branching 
Statements in high-level languages such as Pascal and 
BASIC. The generic IF statement is the basis of this capabil- 
ity. Its operand is a symbolic name or an expression. 


The assembler compares the results. If the results are true, the 
assembler processes the statement following the IF statement. 
If the results are false, the assembler does not process the 
statement until it encounters an ENDC (or ELSE) statement. 
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Hence, the ENDC statement marks the end of a conditionally 
assembled program section. In the following example the 
IFEQ statement tests for equality of its operand with zero: 


IFEQ SWITCH 

Idd #0 assembled only if SWITCH = 0 
leax 1,x 

ENDC 


The ELSE statement lets the IF statement select one of two 
program sections to assemble, depending on the truth of the 
IF statement. The assembler processes statements following 
the ELSE statement only if the results of the comparison are 
false. For example: 


IFEQ SWITCH 

Idd #0 assembled only if SWITCH = 0 

leax 1,x 

ELSE 

Idd #1 assembled only if SWITCH is not = 0 
leax —1,x 

ENDC 


You can use multiple IF statements and nest them within 
other IF statements. They cannot, however, have labels. Each 
IF statement performs a different comparison. 


IFEQ_ True if operand equals zero 

IFNE True if operand does not equal zero 

IFLT True if operand is less than zero 

IFLE _ True if operand is less than or equal to zero 
IFGT True if operand is greater than zero 

IFGE _ True if operand is greater than or equal to zero 
LPP I True only during Pass | (no operand) 


You can use the IF statements that test for less than or greater 
to test the relative value of two symbols if they are subtracted 
in the operand expression. For example, 


IFLE MAX-MIN 


is true if MIN is greater then MAX. 
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NAM string 
TTL string 


100 


Note: The logic is reversed, because this statement literally 
means 


IF MAX-MIN <= 0 


The IFP1 statement causes subsequent statements to be pro- 
cessed during Pass 1, but skipped during Pass 2. It is useful 
because it allows program sections that contain only symbolic 
definitions to be processed only once during the assembly. 
Pass | is the only pass during which they are actually pro- 
cessed because they do not generate actual object code 
output. 


The OS9Defs file is a rather large section of such definitions. 
For example, many source files have the following statement 
at the beginning. 


IFP1 
use /dO/defs/OS9Defs 
ENDC 


define or redefine a program name and listing title line that is 
printed on the first line of each listing page’s header. 


These statements cannot have label or comment fields. 


These statements display the program name on the left side of 
the second line of each listing page; a dash and the title line 
follow. You may change the name and title as often as you 
wish. 


Examples: 


nam DATAC 
ttl Data Acquisition System 


Generates: 


Datac - Data Acquisition System 
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OPT <option> 


sets or resets any of several assembler control options. 


The operand of the OPT statement is one of the characters 
that represents the various options. If a minus sign (— ) pre- 
cedes the option name, the option is turned off; otherwise, it 
is turned on. Two exceptions are the D and W options, which 
must be followed by a number. This statement must not have 
label or comment fields. 


Option Default (initial) State 


G 


Dnum 


Conditionals On — displays conditional assembly 
statements in the listing. (C) 


Page Depth — sets the number of lines per listing 
page, including heading and blank line. (D66) 


Error Messages On — displays error messages in 
listing. When this option is off, an E appears in 
a statement’s informational field if an error is 
present. (E) 


Use Form Feed — uses a form feed for page eject 
instead of line feeds. (—F) 


Generate All Constant Lines — displays all lines 
of code generated by pseudo instructions. Other- 
wise, it displays only the first line. (— G) 


Listing On — generates formatted assembly list- 
ing. If off, the assembler displays only error mes- 
saces. (= L) 


Mode On — turns on Motorola-compatible 
mode. (—M) 
Narrow Listing — generates listing in a non- 


columnized, compressed format for better pre- 
sentation on narrow video display devices. (—N) 


[ = file name | generates object code file: (— O) 
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Wnum 


Examples: 


opt | 


If you do not specify a file name, the assembler 
creates an object file having the same name as the 
input file in the current execution directory. 


If you specify a single name, the assembler cre- 
ates an object file having that name but still in the 
current execution directory. 


If you specify a full pathlist, the assembler uses it 
as the name specification of the device, directory, 
and file to create. 


Generate Symbol Table — displays the entire 
contents of the symbol table at the end of the 
assembly. Displays each name, its value, and a 
type code character: 


D = data variable (RMB definitions) 
E = equate label (EQU) 

L = program label 

S = set label 

U = undefined name 


The table is displayed across the page in alpha- 
betical order. (—S) 


Set Page Width — defines the maximum length 
of each listing line. Lines are truncated if they 
exceed this number. The comment field starts at 
column 50; therefore, a number smaller than this 
may cause important parts of the listing to be lost. 
(W80) 


opt w/2 


opt s 
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ORG <expression> 


PAG[E] 


SPC <expression> | 


changes the value of the assembler’s data location counter 
(normal mode) or the instruction location counter (Motorola- 
compatible mode). 


It evaluates the expression and sets the appropriate counter to 
the value of the result. ORG statements cannot have labels. 


Note: OS-9 does not use load records that specify absolute 
addresses of the generated object code. The object code is 
assumed to be a contiguous memory module. Therefore, pro- 
grams assembled using the Motorola-compatible mode that alter 
the instruction address counter do not load correctly. 


Examples: 
ORG DATAMEN 


ORG .+200 


begins a new page of the listing. The alternate form of PAG is 
PAGE for Motorola compatibility. 


puts blank lines in the listing. 


The value of the operand, which can be an expression, constant, 
or name, determines the number of blank lines to be generated. 
If you use no operand, a single blank line is generated. 


The above two statements improve the readability of program 
listings. They are not themselves displayed and cannot have 
labels. 


SETDP <expression> 


assigns a value to the assembler’s internal direct page counter, 
which is used to automatically select direct versus extended 
addressing. 


103 


USE pathlist 
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The direct page counter does not necessarily correspond to the 
program’s actual direct page register during execution. The 
default value of the counter is zero and should not be changed in 
OS-9 programs; this statement is intended for use with the 
Motorola-compatible mode only. SETDP statements cannot 
have labels. 


temporarily stops the assembler from reading the current input 
file. It then requests OS-9 to open another file or device speci- 
fied by the pathlist, from which it reads input lines until an 
end-of-file occurs. At that point, the assembler closes the latest 
file and resumes reading the previous file from the statement 
following the USE statement. 


You can nest USE statements (for example, a file being read as 
the result of a USE statement can also perform USE statements) 
up to the number of simultaneously open files the operating 
system allows (usually 13, not including the standard I/O 
paths). Some useful applications of the USE statement are to 
accept interactive input from the keyboard during assembly of a 
disk file (as in USE/TERM) and to include library definitions or 
subroutines into other programs. USE statements cannot have 
labels. 
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7/ DEFS Files: Fact or Fiction 


OS9IDEFS 


Most programmers use the OS9Defs file with assembly- 
language programs and add their own definitions to this file. To 
include the OS9Defs file with your source code when assemb- 
ling the file, use the following statements: 

IFP1 

USE /D0/DEFS/OS9DEFS 

ENDC 
This speeds up assembly and prevents the OS9Defs file from 
being displayed every time. 


OS9Defs contains the following groups of defined symbols: 


System Service Request Code 
Signal Codes 

Status Codes For Getstat/Putstat 
Direct Page Variables 

Table Size 

Module Format and Offsets 
Module Field Definitions 
Module Type/Language Masks and Definitions 
Process Descriptor 

Process Status Flags 

OS-9 System Entry Vectors 
Path Descriptor Offsets 

File Access Modes 

Pathlist Special Symbols 

File Manager Entry Offsets 
Device Driver Entry Offsets 
Device Table Format 

Device Static Storage Offsets 
Interrupt Polling Table Format 
Register Offsets on Stack 
Condition Code Bits 

System Error Codes 

I/O Error Codes 


This chapter is a reference source, not a guide to the structure 
and workings of the operating system. For more extensive 
information, see OS-9 Technical Information. 
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System Service Request Codes 


Signal Codes 


a group of labels that define all OS-9 system calls and list their 
associated values. These labels let you use the system request 
name in an OS-9 call. 


a group of labels that define the four OS-9 signals and their 
associated values. This is an appropriate place for your own user 
defined signals. 


Status Codes for GetStt and SetStt 


a group of labels that list and give the values for the predefined 
status call functions of the system calls ISGetStt and I$SetStt 
that are supported by OS-9 file managers and device drivers. 
These labels are then available for loading the B register before 
the call is made. This is an appropriate place for your own user 
defined status codes. 


Direct Page Variables 


Table Size 
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a group of labels that define the offsets into page 0 of OS-9 
system variables. OS-9 uses page 0 variables for interrupt vec- 
tors, table addresses, process queues, and internal memory 
information. We strongly recommend that you not use page 0 
variables in your programs, unless you write special drivers and 
interrupt handlers or debug systems. Using these variables im- 
properly can cause unexpected and perhaps fatal system 
operation. 


a group of equates that define the size of the table that the OS-9 
Operating system uses internally. 
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Module Format and Offsets 


a group of labels that define the offsets into a module header of 
all OS-9 compatible modules. You can use module offsets to 
find information in a module, for example, the module’s size, 
name, type, or language. In this group are the Universal Module 
offsets and the offsets for specific module types. Descriptors, 
drivers, programs, and file managers have a different module 
format. 


Module Field Definitions 
Module Type/Language Masks and Offsets 
Module Attributes/Revision Masks and Offsets 


Process Descriptor 


a group of symbols that define the bits of information that go 
into a module header. You can use this section to decode a 
module header and modify one. Since the OS-9 Interactive 
Assembler generates a module header with the MOD and 
EMOD, use these symbols to read a header. This group defines 
masks according to type, language, attribute, and revision bytes 
and lists the values for each field. 


contains the table of information describing a process. 


Process Status Flags 


define the flags that OS-9 uses to mark a process for different 
states, for example, dead and sleeping. 


OS-9 System Entry Vectors 


a group of symbols that define OS-9 system entry points. These 
are the vector addresses for the various interrupts. They are 
pseudo vectors, not actual hardware vector points. 
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Path Descriptor Offsets 


a group of symbols that define the offsets for OS-9 path descrip- 
tors. OS-9 creates a path descriptor offset for every path opened 
in the system. 


File Access Modes 


a group of symbols that define the file access modes under 
OS-9. You can use these definitions for I$Create and I$Open 
system calls that require the file attributes to be set at the time of 
the call. 


Pathlist Special Symbols 


a group of symbols that define the special pathlist characters. 
You can use them to parse a pathlist. This is an appropriate place 
to insert special characters that you use frequently. 


File Manager Entry Offsets 


a group of symbols that define the entry offsets of all file 
managers on an OS-9 system. If you write your own file man- 
ager, you must provide these entry offsets. 


Device Driver Entry Offsets 


a group of symbols that define all entry offsets of device drivers 
in the OS-9 system. You must provide these offsets at the 
beginning of your drivers. 


Device Table Format 


a group of symbols that define the form of the table that contains 
an entry for every active device in the OS-9 system. The 
operating system uses this information internally. 


Device Static Storage Offsets 


a group of symbols that define the variables within a device 
static storage area. This area contains information about the 
device and is filled in when the device is activated. The actual 


108 


@9@eeeeeeeeeeeeeeeeeeeaeeeeeeeeeeeeed € 


»@eeoeeeeeeeeeeeegeeeeegeoeeeeedeeedeeeee@ 


filling in of the parameters is done by three sources: IOMAN, 
the file manager, and the device driver. The offsets listed in this 
area are filled in by IOMAN. 


Interrupt Polling Table Format 


a group of symbols that define the structure of the entries for the 
polling table. The format contains all the information the inter- 
rupt service routine needs to handle interrupts generated by 
active devices. OS-9 uses this information internally. 


Register Offsets on Stack 


a group of symbols that define the offset to the registers that are 
pushed on the stack whenever the 6809 CPU gets an interrupt of 
the form NMI, IRQ, SWI, SWI2 (an OS-9 system call), or 
SWI3. You can use these symbols when writing drivers to get 
the I$GetStt or ISSetStt codes. You can also use them to pass 
parameters on the stack to different procedures in a program. 


Condition Code Bits 


a group of symbols that define the values for each condition 
code. Use these masks to set or reset the bits. It is good 
programming practice to use these labels in your code. 


System Error Codes 
I/O Error Codes 


a group of labels that define all errors returned by OS-9 and the 
I/O handlers. If your programs have any form of error trapping, 
you must compare the error to a known error definition in order 
to determine what should occur. 
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SCFDEFS 


In this file are the definitions pertaining to the sequential file 
manager and sequential file devices. It contains the following 
groups of defined symbols: 


Static Storage Requirements 
Character Definitions 
File Descriptor Offsets 


You can use this file when writing drivers for sequential devices 
and managers. This is an appropriate place for your own SCF 
definitions. For more information on any group of defined 
symbols, see the OS-9 Technical Information. 


Static Storage Requirements 


a group of symbols that define the offsets to the static storage 
required by SCF devices. This area continues from V.USER 
defined in OS9DEFS. SCF devices must reserve this space for 
the SCF manager. The driver determines the storage reserved 
after this group. 


Character Definitions 


a group of symbols that are defined so that certain SCF devices 
can filter special characters. This is an appropriate place for 
adding your own SCF special characters. 


File Descriptor Format 
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a group of symbols that describe the file manager’s parameters. 
The actual total storage is declared in OS9Defs under the entry 
called Path Descriptor Offsets. Both SCF and RBF have their 
own definitions of the PD.FST and PD.OPT fields. This is 
where SCF’s definitions are located. 
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RBFDEFS 


In this file are the definitions pertaining to random block file 
managers and random file devices. It contains the following 
groups of defined symbols: 


Random Block Path Descriptor Format 
State Flags 

Device Descriptor Format 

File Descriptor Format 

Segment List Entry Format 

Directory Entry Format 

Static Storage 


You can use this file when writing random block file managers 
and devices. This is the appropriate place for adding your own 
RBF definitions. 


Random Block Path Descriptor Format 


a group of symbols that define the file descriptor offsets for RBF 
devices. The actual total storage is declared in OS9DEFS under 
Path Descriptor Offsets. Both SCF and RBF have their own 
definitions of the PS.FST and PD.OPT fields. This is where 
RBF’s definitions are located. 


State Flags 


a group of symbols that define the flags that OS-9 uses internally 
to mark the state of the disk buffer. 


Device Descriptor Format 


a group of symbols that define the format of the contents of 
sector zero of an RBF device. RBF uses this format to find the 
actual physical information on the device. OS-9 uses this in- 
formation to fill in the drive table. This differs from SCF type 
devices in that the actual device information is kept on the 
media. The device descriptor in memory is then mainly used by 
the format program. 
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File Descriptor Format 


a group of symbols that defines a format that is kept on disk and 
contains information on the file, for example, its size, segment 
list, and owner. RBF reads in this information and uses it when 
accessing a file. Whenever you modify the file, this sector is 
modified. 


Segment List Entry Format 


a group of symbols that define an entry ina file segment list. The 
actual list is composed of the beginning sector and the size (in 
number of sectors) of each segment of the file. Files that have 
extensions also have an additional segment for the segment list. 


Directory Entry Format 


Static Storage 
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two symbols that define a directory entry, the file name and the 
file descriptor sector address. 


a group of symbols that define the size and format of the drive 
tables allocated by the driver. The drive tables begin at 
DRVBEG and continue to DRVMEM. Also V.NDRY is allo- 
cated before the tables and defines the number of drives and 
therefore the number of tables used by a driver. The rest of the 
static storage is defined in OS9DEFS and in the driver. You can 
use this information when writing your RBF device driver. 
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SYSTYPE 


This file contains descriptions of the physical parameters of the 
various OS-9 systems. Some of those parameters are: 


CPU Type Definitions 
CPU Speed Definitions 
Disk Controller Definitions 
Clock Module Definitions 
PIA Type Definitions 
System Type Definitions 
Disk Port Address 

Disk Definition 

Disk Parameters 

Clock Port 

I/O Port 


You can use this file when writing or modifying drivers. All the 
necessary information is supplied on the file. 
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8 / Assembly-Language 
Programming Techniques 


For your program to run correctly in the OS-9 environment, it 
must be position-independent, and all memory locations mod- 
ified by the program (variables and data structures) must be in 
an area that OS-9 assigns at run time. 


You have no control over which addresses OS-9 assigns at a 
load area or over where OS-9 assigns the program’s variables. 
Because of the powerful 6809 instruction set and addressing 
modes, these rules do not force you into writing tricky or 
complex programs; rather, they require you to write programs in 
a specific way. 


Your programs usually fall into one of three categories: 


1. A subroutine or subroutine package. You must 
write your subroutines in position independent 
code. Data sections are usually a matter of coor- 
dination with the calling program, and OS-9 nor- 
mally plays no direct role in this. 


2. A program to be executed as an individual process 
(commands are of this type). You must use position 
independent code and receive data area parameters 
that delineate the assigned memory space. 


3. Programs to be run on another, non-OS-9 
computer. 


Program Sections and Data Sections 


If you run your program as a process (by means of the OS-9 
Shell, fork system call, or execute system call), OS-9 assigns 
two separate and distinct memory areas. The program object 
code loads into one memory space in the form of a memory 
module. Variables and data structures load into the other space. 
The program’s module header specifies the minimum permissi- 
ble size for each area. 
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Program Area 


The distinction between these two spaces is extremely impor- 
tant. The data address counter is for the data area, and the 
instruction address counter is for the program area. The values 
of both counters are never absolute addresses. They are relative 
to the beginning of an OS-9-assigned address. 


The program area is a simple, continuously allocated memory 
space where OS-9 loads the program. For OS-9 to load the 
program, it must be in memory module format. OS-9 Technical 
Information contains a detailed description of memory modules 
and how they work. This manual assumes you are familiar with 
them. 


The assembler generates programs that can consist of one or 
more memory modules. It writes them to the same file, and 
OS-9 loads them together. In assembly-language source pro- 
grams, modules usually begin with a MOD pseudo-instruction 
and end with an EMOD pseudo-instruction. These take care of 
the header and module CRC generation for you. 


Never modify the program area by the program itself, especially 
if the program is to be reentrant and/or placed in ROM. It can 
(and should) contain constants and constant tables, as long as 
they are not altered by the program. 


Position Independent Mode 
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You do not know the absolute address of anything in the pro- 
gram until it is run. The 6809 position-independent addressing 
modes are based on ‘‘program counter relative addressing.’’ All 
branch and long-branch instructions use this addressing mode. 


—> Use BRA and LBRA instead of JMP; use BSR and LBSR 
instead of JSR extended or direct mode instructions (indexed 1s 
OK). 
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All load, store, arithmetic, and logical instructions can use the 
program-counter-relative (PCR) indexed addressing mode. 
—> Do not use immediate addressing to load a register with 
an absolute address (instruction label name). Use PCR indexed 
addressing instead. 


Many well-written programs use constant tables of addresses 
(often called dispatch tables or pointer tables). For the program 
to be position independent, these tables cannot contain absolute 
addresses. You must create tables of addresses that are relative 
to an arbitrary location. The routines that use the tables read the 
table entries and then add them to the absolute address of the 
arbitrary location. The sum is the run-time absolute address. 


You can determine the absolute address of the arbitrary location 
by using PCR instructions (typically LEA). The choice of the 
common address is arbitrary, but two places may have specific 
advantages: the beginning address of the table (an index register 
probably will contain this address anyway); and the first byte of 
the module. 


Making table entries relative to the start of the module is 
especially handy because the value of the assembler’s instruc- 
tion address counter is also relative to the beginning address of 
the module. 


In the following example, a routine jumps to one of several 
subroutines, the relative addresses of which are contained in a 
table. The instructions pass the routine to a number in the B 
accumulator, which uses it as an index to select the routine. 


begin mod a,b,c,d,e,f start of module 


(various instructions) 


dispat leax table,pcr get the absolute 
address of the table 
aslb multiply index by 2 
(two bytes/entry) 
Idd_ b,x get contents of table 
entry 
leax begin,pcr vet beginning 
address of module 
jmp d,x add relative address 
and go... 
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table fdb routine | 
fdb routine2 
fdb routine3 
fdb routine4 


In the following example the entries are relative to the beginning 
of the table instead of to the beginning of the module. 


dispat leax table ,pcr get the absolute 
address of the table 

aslb multiply index by 2 
Idd b,x get routine offset 
jmp d,x add and go... 

table fdb routine 1-table 
fdb routine2-table 
fdb routine3-table 
fdb routine4-table 


The above example contains fewer instructions. It is also faster 
because the register already contained the reference address ina 
register; therefore, you can eliminate a LEAX instruction. This 
technique is also useful for accessing character strings, con- 
stants, complex data types, and so on. 


Accessing the Data Area 
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The “‘minimum permanent storage size’’ entry of the module 
header specifies the size of the data area. A program may, 
however, occupy more than this minimum. OS-9 allocates 
memory in multiples of 256-byte pages, and it allocates all 
processes at least one page. The data area must be large enough 
for all the program’s variables and data structures, plus a stack 
(at least 250 bytes) and space to receive parameters. 


When OS-9 calls the process, it passes the bounds of the data 
area to the process in the Registers MPU. U contains the 
beginning address, and Y contains the ending address. It sets the 
Register SP to the ending address + 1, unless parameters were 
passed. It sets the direct page register to the page number of the 
beginning page. 
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In the assembly-language source program, you can assign stor- 
age in the data area with the RMB pseudo instruction, which 
uses the separate data address counter. You need to declare all 
variables and structures at the beginning of the program. De- 
clare smaller, frequently used variables first. They usually fit in 
the first page, and you can access them with short, fast direct- 
page addressing instructions. Follow with larger items. You can 
address them in two ways: 


1. If you maintain Register throughout the program, 
use constant-offset-indexed addressing. 


2. Part of the program’s initialization routine can com- 
pute the actual addresses of the data structures and 
store them in pointer locations in the direct page. 
Obtain the addresses later with direct-page addres- 
sing mode instructions. 


Note: You cannot use program-counter relative addressing to 
obtain addresses of objects in the data section, because the 
memory addresses assigned to the program section and the 
address section are not a fixed distance apart. Of course, im- 
mediate and extended addressing are not generally usable. 


The following example illustrates the U relative technique. 


* declare variables 


temp1 rmb 2 
temp2 rmb 2 
buf1 rmb 400 
buf2 rmb 400 
buf3 rmb 400 


119 


120 


leax bufl,u 
bsr clrbuf 
leax buf2,u 
bsr clrbuf 
leax buf3,u 
bsr clrbuf 


clrbuf 
cloop 


* clear each 400-byte buffer 


get address of buf] 
get address of buf2 
get address of buf3 
* clear buffer subroutine 
* X = address of buffer 
Idd #400 = byte count 
clr ,.x+ clear byte and advance pointer 
subd #1 decrement count 
bne cloop loop if not done yet 
rts 
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9 / Assembler Error Reporting 


When the assembler detects an error, it displays an error mes- 
sage just before the line containing the error. If a statement has 
two or more errors, the assembler displays each error on a 
different line preceding the erroneous line. 


If the -L option inhibits the assembler, the assembler still 
displays error messages and erroneous lines. The statistical 
summary displayed at the end of the assembly contains the total 
numbers of errors and warnings. The assembler writes the error 
messages, erroneous source lines, and the assembly summary to 
the assembler task’s error and status path, which the shell may 
redirect. The assembler writes the listing to the output path, 
which it may redirect independently of the error messages. This 
is useful when a procedure file calls the assembler. Example: 


asm sourcefile — 10 >same.listing >>save.errs 


You can perform a quick assembly just to check for errors by 
calling the assembler with the listing and object code generation 
both disabled by the —L —O options. In this way you can find 
and correct many errors before displaying a lengthy list. 
Example: 


asm sourcefile —1 —0O 


The — E option turns off error-message display, but you can still 
detect lines containing errors by the presence of an E in the 
informational column of the listing line. You may want to use 
this option to generate a ‘‘cleaner’’ listing of a program known 
to have many errors. 


Sometimes the assembler stops processing an erroneous line, 
and therefore you may not be able to detect additional errors on 
the same line; so make corrections carefully. 


Explanation of Error Messages 


Error messages consist of brief phases that describe the error. 
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Syntax and Grammar Errors 


Improperly constructing source statements can cause the fol- 
lowing errors of syntax and grammar. 


ADDRESS MODE. The addressing mode specified is not 
legal for the instruction. 


BAD INSTR. The assembler does not recognize the in- 
struction given in the source statement. 


BAD LABEL. The statement’s label contains an illegal 
character or does not begin with an alphabetical character. 


|] MISSING. A closing bracket is missing. 


CONST DEF. The instruction requires a constant or an 
expression that is missing or in error. 


INDEX REG. The instruction requires the name of an 
index register but none was found. 


LABEL NOT ALLOWED. This type of statement cannot 
have a label. 


NEEDS LABEL. The statement must have a label. 


OUT OF RANGE. The destination (label) of the branch is 
too far to use a short-branch instruction. 


REG NAM. The required register name is missing or 
misspelled. 


REG SIZES. The registers specified in a TFR or EXG 
instruction are of different lengths. 


Arithmetic Errors 


Improper arithmetic or the use of improper arithmetic expres- 
sions can result in the following errors. 


DIV BY O. A division with a zero divisor occurred. 
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EXPR SYNTAX. The arithmetic instruction is illegally 
constructed or is missing an operand following an 
operator. 


IN NUMBER. A constant number (decimal, hexa- 
decimal, or binary) is too large or contains an illegal 
character. 


MULT OVEREL. The result of a multiplication is more 
than 65,535 (two bytes). 


PARENS. The expression contains an unequal number of 
right and left parentheses. 


RESULT>255. The result of the expression is too large 
to fit in the 1-byte value used by the instruction. 


Symbolic Name Errors 


When symbolic names are improperly used, defined, or rede- 
fined, the following errors can occur. 


PHASING. The statement’s label had a different address 
during the first assembly pass. This usually happens when 
an instruction changes addressing modes, and thus its 
length, after the first pass because its operand becomes 
defined after the source line is processed. Usually the 
error occurs on all labels following the offending source 
line. 


REDEFINED NAME. The label was defined previously 
in the program. 


UNDEFINED NAME. The symbolic name was never 
defined in the program. 
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Assembler Operational Errors 
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Using the assembler incorrectly can cause the following errors. 


CAN’T OPEN PATH. The file cannot be opened (source 
file) or created (object file). 


INPUT PATH. The input path contains a read error. 


MEMORY FULL. The symbol table is full. More mem- 
ory is required to assemble the program. 


OBJECT PATH. The object file contains a write error. 


OPT LIST. The assembler command line or an OPT 
statement contains an illegal option or is missing an 
option. 
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Appendix A / Sample Command 
Lines 


asm disk—crash 


assembles the file disk_crash. 

This command does not create a listing or an object file. It 
reports error to the standard error path and establishes 4K 
memory for symbols (asm default). 


asm work.rec 0 #16k 


assembles the file work.rec. 

This command does not create a listing. It does create an object 
file with the name work.rec in the current commands directory. 
It reports errors to the standard output path and establishes 16K 
memory for symbols. 


asm tyco 0=/d0/cmds/tyco.obj 1 #16k 


assembles the file tyco. 

This command creates a listing directed at the standard output 
and an object file with the name tyco in the /dO/cmds directory. 
It reports errors to the listing path and establishes 16K memory 
for symbols. 


asm it_works 0,1 #16k >/p 


assembles the file it_works. 

This command creates a listing directed at /p and an object file 
with the name it_works in the current commands directory. It 
reports errors to the listing path and establishes 16K memory for 
symbols. 


asm test_util 1,s,w72,d25 #10k 


assembles the file test_util. 

This command creates a listing directed at the standard output. 
The listing has 25-line pages and 72-column lines. It does not 
create an object file. It establishes 10K memory for symbols and 
creates a symbol table. It reports errors to the listing path. 
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asm /term i 1 o=d0/progs/woof 
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assembles input from the terminal. 

This command creates a listing directed at the standard output 
and an object file with the name woof in the /dO progs directory. 
It reports errors to the listing path and establishes 4K memory 
for symbols (asm default). 
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Appendix B / Error Messages 
Abridged 


The assembler displays an error message for each error it de- 
tects. It displays the messages before the line in which the error 
occurs. You can suppress the display of error messages by using 
the —E command. 


ADDRESS MODE. The specified addressing mode is not 
legal for the instruction. 


BAD INSTR. The assembler does not recognize the in- 
struction given in the source statement. 


BAD LABEL. The statement’s label contains an illegal 
character or does not begin with a letter. 


| MISSING. A closing bracket is missing. 
CAN’T OPEN PATH. The file cannot be opened. 


CONST DEF. A constant expression is missing or in 
error. 


DIV BY 0O. A division with a zero divisor occurred. 


EXPR SYNTAX. The arithmetic instruction is illegally 
constructed or is missing an operand following an 
operator. 


INDEX REG. The name of an index register is required 
but none was found. 


IN NUMBER. A constant number (decimal, hexa- 
decimal, or binary) is too large or contains an illegal 
character. 


INPUT PATH. The input path contains a read error. 


LABEL NOT ALLOWED. The statement cannot have a 
label. 


MEMORY FULL. The symbol table is full; create more 
memory to assemble the program. 


MULT OVEREL. The result of a multiplication is more 
than 65,535. 


NEEDS LABEL. The statement requires a label. 
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OBJECT PATH. The object file path contains a write 
error. 


OPT LIST. An option is illegal or missing. 


OUT OF RANGE. The destination of the branch is too far 
to use a short-branch instruction. 


PARENS. The expression contains an unequal number of 
right and left parentheses. 


PHASING. The value of the instruction address or data 
address counter was different during Pass 1; that is, an 
instruction changed addressing modes and length during 
Pass.2. 


REDEFINED NAME. The label was defined previously 
in the program. 


REG NAM. A register name is missing or misspelled. 


REG SIZES. The registers specified in a TFR or EXG 
instruction are of different sizes. 


RESULT>255. The result of the expression is too large 
to fit in the required byte. 
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Appendix C / Assembly Language 
Programming 
Examples 


The following pages contain three assembly language program- 
ming examples. They are: 


UpDn -Program to convert input case to upper or 
lower. 
P -Parallel interface descriptor. 


These programs are provided to give an example of what an 
assembly language program should be in the way of structure 
and form. They also provide the programmer with a guide to 
three of the main program types. 
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UpDn — Assembly Language 
Programming Example 


% 
* this is a Program to convert characters from 
% lower to uPpPer case (by using the u option) 
* the method of Passing the Paramters through 
¥ os9 is used here (system calls) 
* to use tyPe 
* "uPpdn uCopt for lower to upper) ¢{’input’ * ‘outeput’" 
* 
nam UpDn 
* file include in assembly 
ifpl 
use /D@/defs/osSdefs 
endc 
¥ 
* 05-9 System Definition File Included 
es 
oPt 1 
ttl Assembly Language Example 
€ 


* module header macro 


* 
Q222O8 B7CDAOSD mod UDSI2Z+UDNAM;+TYPE+REYVS +START »SIZE 
Q222D 7S7@G4HEE UDNAM fes /updn/ module name for memory 
OBil TIPE set PRGRM+OBJCT mod tyre 
O28 1 REVS set REENT+1 mod revision 

ea 

* storage area for variables 

ra 
D 200d TEMP rib , temP storage for read 
D @aa1 UPRBND rit i Storage for upperbound 
D @202 LWRBND rink 1 storage for lowerbound 
D 2883 rmb 8 25¢ storage for stack 
D @2FD rmb 200 storage for Parameters 
oy O1CS SIZE esi ' end of data area 

4 

* actual code starts here 

* X register if Pointing to start of Parameter area 

* y pegister is Pointing to end of Parameter area 

* this is how to get a Parameter that is Passed on 

¥ the command line and where to look for it 

4 
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OO2F 
QO31 
0033 
0037 
QO3A 
@B3C 
QO3E 
B40 
@B42 
O44 
2846 
2048 
OO4A 
2O4B 
QO4E 
OO4F 
@O51 
G053 
G055 
2056 
8059 
GO5C 


START eqit 


Start of executable 
S@arch Parameter area 


make WPPer case 

see if a U was input 
branch to set uwPPercase 
see if a carriage return 
go get another char 


get lower bound 

set it in storage area 
get upper bound 

set it in storage area 
go to start of code 


get lower bound 
set it in storage 
get upper bound 
set it in storage 


get storage address 
Standard input 

number of characters 
do the read 

Oxit if erro? 

get character read 
test char bound 
branch if out 

test char bound 
Orancn if out 

flip case bit 

Put it in storage 

reg ‘a’ stand output 
Write the character 
return to stand input 
get char if mo error 
is it an EDF error 
not eof+s leave carry 
clear carry, no error 
error returned+s exit 


AGBO SRCH lda xt 
BAD anda #$df 
8155 cmPa #°U 
ZI@E beq UPPER 
81D cmPa #$0d 
2£6F4 brine SRCH 

* 

* fall through to set upper to lower bounds 
- 

8641 lda #°A 
9702 sta LWRBND 
BE5A lda #2 
9701 sta UPRBND 
2008 bra STARTI 
# 

* set lower to upper bounds 

+ 

8661 UPPER lda #’a 
9702 Sta LWRBND 
867A lda #’2z 
9701 sta UPRBND 
% 

* converting code 

* this Part uses the I$READ and 
% the I$WRIT system calls 

* read the systems Programmers manual 
* for information relating to them 
30@C4 START I leax temPeru 
BESO lda #@ 
I@BEBAO1 ldy ##@1 
1@3F89 LOOP os9 I#READ 
Zonn bes XIT 
DESO ldb TEMP 
D1ig2 cmPeb WRBND 
2906 blo WRITE 
Di@i cmpPpb UPRBND 
2202 bhi WRITE 
C820 eorb #$290 
D78O WRITE stp TEMP 
4C inca 

i@3FB8A os9 IJ#WRITE 
4A deca 

Z4EG pec EOOGP 
C1D3 Ae cmPpb #E$EOF 
2601 brie Aid 
od as Gi Th 

193F 06 EXIT 669 FEXTT 
Z6@4D9 emod 


UDSTZ equ * 
END 


last command 
size of Program 


131 


P - Device Descriptor for "P" 


Nain P 


ifel 
endc 


tt 1 Device Descriptor for "P" 
KHEKKKKHHHHKKHK KEES 


¥% PRINTER device module 


ra 

2000 87CD@835 mod PRTEND+PRTNAM+DEYVIC+OBJCT + 
REENT+1 +PRTMGR +PRTDRY 

O202D O82 fob WRITE mode 
QOGE FF TGR SPF 
QOOF ESAS Teh AvP Port address 
O2Z1ii 18 fob PRTNAM-*¥-loPtion byte count 
OG1iz a Teh DiaSCr Device Type: SCF 


* Default Path options 


2013 B28 ‘cb case=UPPER and lower 
OG1id a fob @ backsPace=BS char only 
00135 1 Tete: 4 delete=CRLF 

2G1G a tcp +6 mo auto echo 

O201i7 1 fob 1 auto line feed on 
0018 OO fob @ no nulls after CR 
2019 ae fob @ no Page Pause 

Q@G1iA 42 feb 6S lines Per Page 

O221iB @8 feb CeBSP backspace char 

@21iC 18 Teo CSPEL delete line char 
201D @D fcb C#CR end of record char 
QG1iE OO fob @ no end of file char 
QBiF od feb C#RPRT reprint line char 
OPG2Q0 Oi feb C#RPET dup last line char 
O221 17 feb C#PAUS Pause char 

OB22 8 fob @ no abort character 
O223 OO fob @ no interrupt character 
OO24 SF fcb wa backsPace echo char 
Q8253 07 feb C#BELL line overflow char 
B26 1 feb PIASID Printer Type 

Q2B827 OO Teb @ undefined baud rate 
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ASB1i18 


PRTNAM 


PRTMGR 
PRTDRY 


PRTEND 


fob 
fos 
fos 
fos 
fos 


emod 


EQU 
END 


2 
wpe 
al 1 Say 
"SCF" 
"PIA" 


% 


no echo device 

device name 

room for name Patching 
file manager 

driver 
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Appendix D / 6809 Instructions And 
Addressing Modes 


DIRECT EXTEND INDEX IMMED ACCUM INHER RELAT REGIS 


ABX x 

ADCA x X x X 

ADCB x . x X 

ADDA x x - x 

ADDB x x X X 

ADDD X x = * 

ANDA : 4 X X 

ANDB x X X X 

ANDCC x 

ASL x x = 

ASLA x 

ASLB X 

ASR x X x 

ASRA X 

ASRB X 

(L)BCC 5 
(L)BCS x 
(L)BEQ X 
(L)BGE x 
(L)BGT X 
(L)BGI x 
(L)BHS x 
BITA X x X x 

BITB x = x x 

(L)BLE x 
(L)BLO x 
(L)BLS X 
(L)BLT 4 
(L)BMI x 
(L)BNE X 
(L)BPL x 
(L)BRA - 
(L)BRN x 
(L)BSR x 
(L)BVC X 
(L)BVS . 
CLR Ps X x x 

CMPA 5 x X x 

CMPB x x < X 

CMPD x X X X 

CMPS x x X x 

CMPU x x * x 

CMPX x ¥ x x 

CMPY X > > X 

COM x p bs x 

CWAI x 

DAA X 

DEC x x x ys x 

EORA x X x x 

EORB x X X x 
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sae 
|x >< > > Se 
me 
i 
_ 
a 
a 
2 
= 
= < > be >< > > > 
Z. 
=> 
5 
Oo] x > Od >< >< >< 
© 
_ 
= 
S bd >d Dt dd Od OOK <> >< dd > x 
= 
a 
Bl x xX KD DO OOO D> > DD OOOO od 
Z. 
ra 
Z. 
on > >< > DD OO OOOO >< 
A 
my 
5 
| bd MO <> bt >< >< > DD OOOO >< 
a 
nD Kx ea ne = y= 2 <a aon UV 
COR eK RANROKR Cee ey eS OAT MOF RADA KL DOOM te mn Dem GaaH see ee os 
DOmxee egeg= = 
De Daa PSS SSE EP POORER AREER EERE DDD ee eR EO ae 


1900080808080 8000800808008008080808000000000800808080 


SYMBOL 


DC3(XOFF) 
DC4 

NAK 

SYN 


HEX 


SYMBOL 


Oona n nb WN kK CO ™ >: 


POMS Rr ASS DOM MOAae Se V I Ax > 


HEX 
VALUE 


= | 


Sn * Set cere nrn QdUvos Bere er TM tA Sh 


SYMBOL HEX 
VALUE 


56 
a 
58 
59 
SA 
SB 
1 
SD 
SE 
oF 
60 
61 
62 
63 


Appendix E / ASCII Character Set 
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SYMBOL 


” & 


a= rra~-_~ 
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HEX 
VALUE 


26 
2] 
28 
29 
30 


SYMBOL 


CHADD 


HEX 
VALUE 


51 
= 
he 
54 
55 


SYMBOL HEX 


VALUE 


(:% 
7D 
TE 
#8 5) 
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OS-9 Interactive Debugger 
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1 / Introduction 


DEBUG is an interactive debugger that aids in diagnosing 
systems and testing 6809 machine-language programs. You can 
also use it to gain direct access to the computer’s memory. 
DEBUG’s calculator mode can simplify address computation, 
radix conversion, and other mathematical problems. 


Calling DEBUG 


DEBUG is supplied on your OS-9 system disk. When the screen 
shows the OS-9 prompt, call DEBUG by typing: 


DEBUG (ENTER 


Basic Concepts 


DEBUG responds to 1-line commands entered from the 
keyboard. The screen shows the DB: prompt when DEBUG 
expects a command. 


Terminate each line by typing (ENTER). Correct a typing error by 
using the backspace (left arrow) key, or delete the entire line by 


typing (X_) while pressing (CLEAR). 


Each command starts with a single character, which may be 
followed by text or by one or two arithmetic expressions, 
depending on the command. You may use upper- or lower-case 
letters or a mixture. When you use the to insert a 
space before a specific expression, the screen shows the results 
in hexadecimal and decimal notation. Example: 


In the calculator mode, obtain hexadecimal and decimal nota- 
tion for the hexadecimal expression A+ 2: 
You Type: (HQ) 
Screen Shows: DB: At+2 
$#200GC #00012 
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Note: In the examples in this manual, general instructions are 
followed by specific typing instructions and then by what the 
screen shows. In some cases, examples will follow the explana- 
tion of more than one command. Be sure to execute these 
examples in the exact order in which they are given so that you 
will obtain the specified display on your screen. 


©900600080080808008080808080808080008O00088OCeCCOC OE 
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2 / Expressions 


Constants 


DEBUG’ s integral expression interpreter lets you type simple or 
complex expressions wherever a command calls for an input 
value. DEBUG expressions are similar to those used with high- 
level languages such as BASIC, except that some extra oper- 
ators and operands are unique to DEBUG. 


Numbers in expressions are 16-bit unsigned integers, which are 
the 6809’s ‘‘native’’ arithmetic representation. The allowable 
range of numbers is 0 to 65535. Two’s complement addition and 
subtraction is performed correctly, but will print out as large 
positive numbers in decimal form. 


Some commands require byte values, and the screen shows an 
error message if the result of an expression is too large to be 
stored in a byte, that is, if the result is greater than 255. Some 
operands, such as individual memory locations and some regis- 
ters, are only one byte long, and they are automatically con- 
verted to 16-bit ‘‘words’’ without sign extension. 


Spaces, other than a space at the beginning of a command, do 
not affect evaluation; use them as necessary between operators 
and operands to improve readability. 


Constants can be in base 2 (binary), base 10 (decimal), or base 
16 (hexadecimal). Binary constants require the prefix %; deci- 
mal constants require the prefix #. All other numbers are 
assumed to be hexadecimal and may have the prefix $. Exam- 
ples: 


Decimal Hexadecimal Binary 
# 100 64 % 1100110 
#255 BP TATALTIALI 
#6000 1770 % 1011101110000 
#65535 PEEP  SESCREER ED SEER EE! 
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You may also use character constants. Use a single quote (’) for 
|-character constants and a double quote (”) for 2- character 
constants. These produce the numerical value of the ASCII 
codes for the character(s) that follow. Examples: 


"A = $0041 
‘0 = $0030 
"AB = $4142 
"99 = $3939 


Special Names 


Dot (.) is DEBUG’s current working address in memory. You 
can examine it, change it, update it, use it in expressions, and 
recall it. Dot eliminates a tremendous amount of memory 
address typing. 


Dot-Dot (..) is the value of Dot before the last time it was 
changed. Use Dot-Dot to restore Dot from an incorrect value or 
use it as a second memory address. 


Register Names 


Specify Registers MPU with a colon (:) followed by the mne- 
monic name of the register. Examples: 


A Accumulator A 

B Accumulator B 

:D Accumulator D 

X X Register 

afb & Y Register 

7U U Register 

-DP Direct Page Register 

‘SP Stack Pointer 

:PC_ ~—- Program Counter 

‘CC Condition Codes Register 
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Operators 


The values returned are the test program’s registers, which are 
‘*stacked’’ when DEBUG is activve. One-byte registers are 
promoted to a word when used in expressions. 


Note: When a breakpoint interrupts a program, the Register SP 
points at the bottom of the Register MPU stack. 


‘*Operators’’ specify arithmetic or logical operations to be per- 
formed within an expression. DEBUG executes operators in the 
following order: (1) — , negative numbers; (2) & and !, logical 
AND and OR; (3) * and /, multiplication and division; (4) + 
and — , addition and subtraction. Operators in a single express- 
ion having equal precedence, for example, + and —, are 
evaluated left to right. You can use parentheses, however, to 
override precedence. 


Forming Expressions 


An expression is composed of any combination of constants, 
register names, special names, and operators. The following are 
valid expressions: 


#1024 + #128 
op, Caer aa 

Yr 20 
>Y*(:X + :A) 


“U & FFFE 
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Indirect Addressing 
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Indirect addressing returns the data at the memory address using 
a value (expression, constant, special name, and so on) as the 
memory address. The two DEBUG indirect addressing modes 


are: 
<expression> 


returns the value of a memory byte using expression as an 
address. 


[expression | 


returns the value of a 16-bit word using expression as an 
address. 


Examples: 
<200> 

returns the value of the byte at Address 200. 
[:X] 

returns the value of the word pointed to by Register X. 
[. +10] 


returns the value of the word at Address Dot plus 10. 


SOCHHOHOSHHSSHSHSHSHSHSHOHSHOHHOHOHOHOHSHOOCHOHOOOOCEE 
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3 / Debug Commands 


Calculator Commands 


SPACEBAR)<expression> (ENTER 


evaluates the expression and displays the results in both hexa- 
decimal and decimal. Examples: 


You Type: (SPACEBAR)3 200+20@ (ENTER 
Screen Shows: DB: 3400+20¢@ 
$5200 #20992 


You Type: (SPACEBAR)88aa/2 (ENTER 
Screen Shows: DB: 88a@@/2 
£4400 #17408 


You Type: (SPACEBAR)#1@¢+#12 (ENTER 
Screen Shows: DB: #1@@+#8#12 
$2070 #00112 


These commands also convert values from one representation to 
another. Examples: 


Convert a binary expression to hexadecimal and decimal: 
You Type: (SPACEBAR)Ziiiigeade 
Screen Shows: DB: Z11i11aaae 

$QQFO #20240 


Convert a l1-character constant to hexadecimal ASCII and dec- 
imal ASCII: 
You Type: ‘A 
Screen Shows: DB: ‘A 
$2041 #4aaG5 


Convert a decimal expression to hexadecimal and decimal: 
You Type: (SPACEBAR)# 122 
Screen Shows: DB: #100 
$20C4 #0010 


You can also use indirect addressing to look at memory without 
changing Dot. Example: 
You Type: 
Screen Shows: DB: . 
$Q2QG4F #090079 
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In addition, you can use indirect addressing to simulate 6809 
indexed or indexed indirect instructions. The following exam- 
ple is the same as the assembly language syntax [D,Y]. 
You Type: (SPACEBAR)[ : D+: 1] 
Screen Shows: DB: [C:D+:¥] 
$2119 #00272 


Dot and Memory Examine and Change 


Commands 
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displays the current value of Dot (the current working memory 
address) and its contents. Example: 


You Type: + (ENTER 
Screen Shows: DB: . 
2201 Be 


The present value of Dot is 2201, and BO is the contents of 
memory location 2201. 


ENTER 


increments Dot and displays its new value and contents. 
Example: 


‘‘Step through’’ sequential memory locations: 


You Type: (ENTER 


Screen Shows: DB: 


You Type: 
Screen Shows: DB: 
2703 C2 
You Type: 
Screen Shows: DB: 
2204 82 
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backs up Dot one address and displays its value and contents. 
Example: 


Display the current value of Dot: 
You Type: « (ENTER 
Screen Shows: DB: . 
2204 82 


Back up one address and display its value and contents: 


You Type: - (ENTER 


Screen Shows: DB: - 
2203 C2 


Back up another address and display its value and contents: 
You Type: - 
Screen Shows: DB: - 
2202 O35 


. expression 


changes the value of Dot. This command evaluates the specified 
expression, which becomes the new value for Dot. Example: 


You Type: + 3@@ (ENTER 
Screen Shows: DB:. 30 
@500 12 


restores the last value of Dot. Example: 


Display the current value of Dot and its contents: 
You Type: « (ENTER 
Screen Shows: DB: . 
1908 23 


Change the value of Dot: 
You Type: . 2@0@@ 
Screen Shows: DB: « £800 
2000 9C 
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Restore the last value of Dot: 

You Type: «+ (ENTER 
Screen Shows: DB: ..+ (ENTER 
1000 23 


= expression 


changes the contents of Dot. This command evaluates the ex- 
pression and stores the results at Dot. It then increments Dot and 
displays the next address and contents. 


This command also checks Dot after the new value is stored to 
make sure it changed to the correct value. If it did not, the screen 
shows an error message. This happens when you attempt to alter 
non-RAM memory. In particular, the registers of many 6800- 
family interface devices (such as PIAs and ACIAs) do not read 
the same as when written to. 

Example: 


Display the current value of Dot and its contents: 
You Type: +. (ENTER 
Screen Shows: DB: . 
2208 GZ 


Change the contents of Dot: 
You Type: =FF 
Screen Shows: DB: =FF 
220d O1 


Show that the contents of Dot have changed: 
You Type: - 
Screen Shows: DB: - 
2293 FF 


Warning: This command can change any memory location. 
You can destroy DEBUG, the program under test, or OS-9 if 
you incorrectly change any of their memory areas. 
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Register Examine and Change Commands 


You can use any of several forms of the colon (:) register 
command to examine one or all registers or to change a specific 
register’s contents. 


The “‘registers’’ affected by these commands are actually **1m- 
ages’’ of the register values of the program under test, which are 
stored on a stack when the program is not running. Although a 
‘‘dummy’’ stack is established automatically when you start 
DEBUG, use the E command to give the register images valid 
data before using the G command to run the program. The 
‘‘registers’’ are valid after breakpoints are encountered and are 
passed back to the program upon the next G command. 


Note: 
1. If you change the Register SP, you move your stack 
and the other register contents change. 
2. Bit 7 of Register CC (the E flag) must always be set 
for the G command to work. If it is not set, DEBUG 
does not return to the program correctly. 


: register 


displays the contents of a specific register. The contents are in 
hexadecimal. Examples: 


You Type: : PC (ENTER 
Screen Shows: DB: :PC 
Cagg9 


You Type: :6 (ENTER 
Screen Shows: DB: :B 
Qa7E 


You Type: : SP (ENTER 
Screen Shows: DB: :5SP 
A2FD 
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displays all registers and their contents. Example: 


You Type: : (ENTER 
Screen Shows: DB: : 
PC=B263 4=01 B=@B CC=8¢@ 
DP=2C 
SP=@CF4 K=FFOD Y=@@00B 
U=2@AE 


:<register> <expression> 


assigns a new value to a register. DEBUG evaluates the ex- 
pression and stores it in the specified register. When you name 
8-bit registers, the value of the expression must fit in a single 
byte. If it does not, the screen shows an error message, and the 
register does not change. Examples: 


You Type: :X #4896 (ENTER 
Screen Shows: DB: :X #4896 


Breakpoint Commands 
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The breakpoint capabilities of DEBUG let you specify ad- 
dresses where you wish to suspend execution of the program 
under test and reenter DEBUG. When you encounter a break- 
point, the screen shows the values of the Registers MPU and the 
DB: prompt. 


After a breakpoint is reached, you can examine or change 
registers, alter memory, and resume program execution. You 
may insert breakpoints at up to 12 addresses. 


You can insert breakpoints by using the 6809 SWI instruction, 
which interrupts the program and saves its complete state on the 
stack. DEBUG automatically inserts and removes SWI instruc- 
tions at the right times; so you do not “‘see’’ them in memory. 


eeegeee@eoeoacoa aoe o5u@ae eee oeoeooeoeooeoeooeooeoeoeoeoeoeoeoee eee @ 
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Because the SWIs operate by temporarily replacing an instruc- 


tion OP code, there are three restrictions on their use: 


1. | You cannot use breakpoints in programs in ROM. 


2. You must locate breakpoints in the first byte (OP 


code) of the instruction. 


3. You cannot utilize the SWI instruction in user pro- 
grams for other purposes. (You can use SWI2 and 


SWI3.) 


When you encounter the breakpoint during execution of the 
program under test, reenter DEBUG by typing <:><register 
name>. The screen shows the program’s register contents. 


B 


displays all present breakpoint addresses. 


B <expression> 
inserts a breakpoint at a specified expression. 
Examples: 


Insert a breakpoint at the specified expression: 
You Type: B 1C@@ (ENTER 
Screen Shows: DB: B 1Ca@@ 


Insert another breakpoint at the specified expression: 


You Type: B 4FD3 (ENTER 
Screen Shows: DB: B 4FD3 


Display the current value of Dot and its contents: 
You Type: « (ENTER 
Screen Shows: DB: . 
Lee? oe 


Insert the breakpoints at Dot: 
You Type: B .« (ENTER 
Screen Shows: DB: B ,. 
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Display all present breakpoint addresses: 
You Type: B 
Screen Shows: DB: B 
1600 4FD3 1277 


K 


kills (removes) all breakpoints. 


K <expression> 
kills a breakpoint at the specified expression. Examples: 


Display all present breakpoint addresses: 
You Type: B 
Screen Shows: DB: B 
1000 4603 1277 


Kill a breakpoint at the address specified by the expression: 


You Type: K 4FD3 (ENTER 
Screen Shows: DB: K 4FD3 


Display all present breakpoint addresses: 
You Type: B 
Screen Shows: DB: B 
1000 1277 


Kill all breakpoints: 


You Type: K (ENTER 
Screen Shows: DB: K 


Display all present breakpoint addresses: 


You Type: B (ENTER 
Screen Shows: DB: B 
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Program Setup and Run Commands 


E module name 
prepares DEBUG for testing a specific program module. 


This command’s function is similar to that of the OS-9 Shell in 
starting a program. It does not, however, redirect I/O or over- 
ride (#) memory size. The E command sets up a stack, 
parameters, registers, and data memory area in preparation for 
executing the program to be tested. The G command starts the 
program. 


Note: This command allocates program and data area memory 
as appropriate. The new program uses DEBUG’s current stan- 
dard I/O paths, but can open other paths as necessary. In effect, 
DEBUG and the program become coroutines. 


This command is acknowledged by a register dump showing the 
program’s initial register values. The G command begins pro- 
gram execution. The E command sets up the Registers MPU as 
if you had just performed an FSCHAIN service request as shown 
below: 


DP,.U low 


direct page 


data area 


parameter area 


= Parameter area size 
Module entry point absolute address 
CC = (F=0), ([=0) Interrupts disabled 


xs high 


vu 
ol, 
ll | 
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Example: 


Display the program’s initial register values: 
You Type: E myrrogram 
Screen Shows: DB: E myrrogram 
or CO: A &@ DP 
x Y Po 
@CF3 CB @@ G1 OC 
OCFr 8000 9214 


G 


goes to (resumes) program execution after a breakpoint. If a 
breakpoint exists at the present program counter address, that 
breakpoint is not inserted so that it is not immediately reexe- 
cuted. A loop must contain at least two breakpoints if execution 
is to be suspended each time through the loop. 


Note: The E command is usually used before the first G com- 
mand to set up the program to be tested. DEBUG initially sets 
up a default stack; so G expression can be used to start a program 
using the results of the expression as a starting address. 
Examples: 


DB: G 4C00 
DB: G:PC+ 100 
DB: Gt. 


L module name 


links to the module. If successful, it sets Dot to the address of 
the first byte of the program and displays it. You can use L to 
find the starting address of an OS-9 memory module. 


Example: 


Link to the module FEMATH: 
You Type: L FPMATH 
Screen Shows: DB: LFPMATH 
EC@S 87 
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Utility Commands 


C <expressionl> <expression2> 


performs a ‘‘walking bit’? memory test and clears all memory 
between the two evaluated addresses. Expression! gives the 
starting address, and expression2 gives the ending address, 
which must be higher. If any bytes fail the test, this command 
displays their address. Of course, you can test and clear only 
RAM memory. 


Warning: This command can be dangerous. Be sure which 
memory address you are clearing. 


Examples: 


Clear all memory between Addresses 2000 and I5FF: 
You Type: C 15FF 2000 
Screen Shows: DB: C 15FF 2000 
L7ed 
L7E? 


The screen’s display of 17E4 and 17E7 indicates bad memory at 
those addresses. 


Clear all memory between the last value of Dot and Address FF. 
You Type: C . .«+FF (ENTER 
Screen Shows: DB: C . «+FF 


The screen shows a blank line following the command line, 
which indicates good memory. 
M <expressionl> <expression2> 


produces a screen-sized tabular display of memory contents in 
both hexadecimal and ASCII form. 


The starting address of each line is on the left, followed by the 
contents of the subsequent memory locations. On the far right is 
the ASCII representation of the same memory locations. 


Periods are substituted for nondisplayable characters. The high 
order bit is ignored for the display of the ASCII character. 
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S <expressionl> <expression2> 


searches an area of memory for a 1- or 2-byte pattern, beginning 
at the present Dot address. Expression! is the ending address of 
the search, and expression2 is the data for which to search. If 
expression2 is less than 256, a 1-byte comparison is used; if it is 
greater than 256, a 2-byte comparison is used. If a matching 
pattern is found, Dot is set to its address, which is displayed. If a 
matching pattern is not found, the screen shows the DB: prompt. 


$ (ENTER 

calls the OS-9 Shell, which responds with prompts for one or 
more command lines. 

$ Shell Command 

executes the command and returns to DEBUG. 


Also use $ to call the system utility programs and the Interactive 
Assembler from within DEBUG. Examples: 


You Type: #D IR (ENTER 
Screen Shows: DB: $DIR 


DIRECTORY OF ., @@:00:21 


059 BOOT CMDS oro 
vero STARTUP uP Le 
NEWFILE DUSINESS FILE 


Q 


quits (leaves) DEBUG and returns to the OS-9 Shell. Example: 


You Type: 9 (ENTER 
Screen Shows: DB: @ 
OS9: 
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4/ Using Debug 


You use DEBUG primarily to test system memory and I/O 
devices, to ‘‘patch’’ the operating system or other programs, 
and to test hand-written or compiler-generated programs. 


Sample Program 


2OAS 
BBO2 
QOO2 
QO52 
QGE7 
QGEB 


COS 
QOD 


O14 
G14 
@018 
@BiC 
QGiE 
O821 
OO23 
O25 
B29 
Q@V2B 
QOZE 
B38 
0033 
O23 
2038 


Q843 
OBOC 
@ad4 
047 


B87CD8@847 
4358414) 


SVBDABSO 
1Q@BESAOC 
8601 
1Q@3F8C 
2012 
3042 
1Q@BEGASA 
B68 
1Q@3F 8B 
2005 

OOF AS? 
CEOS 
1@3F 06 
48454C4C 


@D 


=68A06 


The simple assembly-language program shown below illus- 
trates the use of DEBUG commands. This program prints 
‘‘HELLO WORLD’”’ and then waits for a line of input. 


NAM 
USE 


* Data Section 


LINLEN 
INPBUF 


STACK 
DATMEM 


*% Program 


NAME 


ENTRY 


ERROR 
OUTSTR 


STRLEN 


ENDPGM 


ORG 
RMB 
RMB 
RMB 
EQU 
EQU 


Secti 
MOD 
FCS 


EQU 
LEAX 
LDY 
LDA 
o2 
CS 
LEAX 
Ly 
LDA 
OS9 
55 
SrTy 
LDB 
usa 
Pi 


FCB 
EQU 
EMOD 
EQU 
END 


EXAMPLE 
/D@/DEFS/@SSDEFS 
0 
2 LINE LENGTH 
Be LINE INPUT BUFFER 
2@ HARDWARE STACK 


or 


DATA AREA MEMORY SIZE 


ENDPGM +NAME +$11+$81 sENTRY »DATMEM 


/EXAMPLE/ 


% 


GUTSTR «PCR 


#STRLEN 
#1 
I$WRITLN 
ERROR 
INPBUF +U 
#80 

# 
IS$READLN 
ERROR 
LINLEN 
#2 
FSEALT 


MODULE NAME STRING 


MODULE. ENTRY POINT 
OUTPUT STRING ADDRESS 
GET STRING LENGTH 
STANDARD OUTPUT PATH 
WRITE THE LINE 

BRA IF ANY ERRORS 
ADDR OF INPUT BUFFER 
MAX OF 8@ CHARACTERS 
STANDARD INPUT PATH 
READ THE LINE 

BRA IF ANY I/O ERRORS 
SAVE THE LINE LENGTH 
RETURN WITH NO ERRORS 
TERMINATE THE PROCESS 


/HELLO WORLD/ OUTPUT STRING 


$2D 
*-OUTSTR 


* 


END OF LINE CHARACTER 
STRING LENGTH 

END OF MODULE 

END OF PROGRAM 
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A Session With DEBUG 
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The following example illustrates how to use DEBUG with the 
program on the previous page. (The actual RAM address may 
vary depending on your computer’s installation of OS-9.) 


OS9:DEBUG #2K 


Interactive Debugger 
DB: $LOAD /D1/EXAMPLE 
DB: L EXAMPLE 


A900 87 
DB: 
A900 87 
DB: M..+44 (dump program on display) 


A900 87CD0047000D1181 ...G.... 
A908 6F00140084455841 O....EXA 
A910 4D504CC5308D0020 MPL.0O.. 
A918 108E000C8601103F ....... z 

A920 8C25123042108E00 .%.0B... 
A928 508600103F8B2505 P...?.%. 
A930 109FO0C600103F06 ...... if 

A938 48454C4C4F20574F HELLO WO 
A940 524C440DDB72DDFF RLD..R.. 


DB: E EXAMPLE (prepare to run program) 
SP CCA B DP xX Y U PG 
ODF3 C8 00 O01 OD ODFF OE00 ODOO 9214 


DB: 

A900 87 
DB: .B .+2E (set breakpoint at address A92E) 
DB: G (run program) 


HELLO WORLD 
hello computer 
ENTER 


BRP? (breakpoint encountered) 
SP CC A B DP. xX Y U PC 
ODF3 CO 00 01 OD ODO2 ODOO ODOO 922E 
DB: M :0 :U+20 — (display register area) 
QAO0O O0010D020000000C ........ 
OA08 OCF400004C000000 ....L... 


SCHOHCHOHSHSHSHHSSSHHSSSHSHSHSSHSHSHSSHSSOSSSCOECOOSE 
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OA10 00000087CD002400 ...... $. 
DATS ODILSIUCOOTZOIC? saan 
0A20 OOQQQOQOQO000FFOOFF 


DBS) . 22 

OAO02 68 
DB: 

OAO03 65 
DB: 

OA04 6C 
DB: 

QA05S 6C 
DB: Q 
OS9: 


Patching Programs 


To ‘‘patch’’ a program (to change its object code), follow these 


five steps: 


ie 


Load the program into memory using OS-9’s 
LOAD command. 


Link to and change the program in memory using 
DEBUG’s L and = commands. 


Save the new, patched version of the program on a 
disk file using OS-9’s SAVE command. 


Update the program module’s CRC check value 
using OS-9’s VERIFY command. Be sure to use the 
U option. 


Set the module’s execute status using OS-9’s ATTR 
command. 


Step 4 is unique to OS-9 (as compared with other operating 
systems) and often overlooked. However, it is essential because 
OS-9 refuses to load the patched program into memory until its 
CRC check value is updated and correct. 


161 


The example that follows shows how the program on page 00 is 
‘*‘patched.’’ In this case the LDY #80 instruction is changed to 
LDY #32. 


OS9: DEBUG (call DEBUG) 

Interactive Debugger 

DB: $LOAD EXAMPLE (call OS-9 to load program) 

DB: L EXAMPLE (set dot to beg addr of program) 
2000 87 (actual address will vary) 

DB: ... .+28 (add offset of byte to change*) 
2028 50 (current value is 00) 

DB =#32 (change to decimal 12) 
2028 10 (change confirmed) 

DB: $SAVE TEMP EXAMPLE (save on file called ‘‘TEMP’’) 

DB: $VERIFY U <TEMP> (update CRC and copy to ‘‘NEWEX’’) 
NEWEX 

DB: $ATTR NEWEX E PE (set execution status) 

DB: $DEL TEMP (delete temporary file) 

DB: q (exit DEBUG) 


Patching OS-9 Component Modules 
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Patching modules that are part of OS-9 (modules contained in 
the OS-9 Boot file) is a bit trickier than patching a regular 
program because you must use the COBBLER and OS-9GEN 
programs to create a new OS-9 Boot file. The example below 
shows how an OS-9 ‘‘device descriptor’’ module is permanent- 
ly patched, in this case to change the upper-case lock of the 
device /TERM from on to off. This example assumes that a 
blank freshly formatted diskette is in Drive | (/D1). 


Caution: Always use a copy of your OS-9 System Disk when 
patching, in case something goes wrong. 


OS9: DEBUG (call DEBUG) 

Interactive Debugger 

DB: L TERM (set dot to addr of TERM module) 
CA82 87 (actual address will vary) 

DB: .. +13 (add offset of byte to change*) 
CA9S5 O01 (current value is 01) 

DB? =1 (change value to 01 for ‘‘OFF’’) 
CA96 01 

DB: — (ENTER (move back one byte) 

CA95 00 (change confirmed) 

DB: :Q (exit DEBUG) 

OS9: COBBLER /D1 (write new bootfile on /D1) 


SO@GOSeeeeeeeeeeeeeeeeeeeeeeaeeeeeeee @ C 


YYYUurereerererereeeueeereeeeeeeeeecueeey 


OS9: VERIFY </D1/OS9BOOT >/D01/TEMP U 
(update CRC value) 
OS9: DEL /D1/OS9BOOT (ENTER) (delete old boot file) 
OS9: COPY /D01/TEMP/D1/OS9BOOT 
(install updated boot file) 


Then you can use the Dsave command to build a new systems 
disk. 
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Appendix / Debug Command 
Summary 


SPACEBAR) expression 


Evaluate; display in hexadecimal 


Dot Commands 


. expression 


= expression 


ENTER 


Register Commands 


sregister 


sregister 
expression 


and decimal. 


Display Dot address and 
contents. 

Restore last DOT, display 
address and contents. 

Set Dot to result, display address 
and contents. 

Set memory at Dot to result. 

Decrement Dot, display address 
and contents. 

Increment Dot, display address 
and contents. 


Display all register contents. 
Display specific register 
contents. 

Set register to result. 


Program Setup and Run Commands 


E module name 
G 

G expression 

L module name 


Breakpoint Commands 


B 
B expression 
K 
K expression 


Prepare for execution. 

Go to program. 

Go to program at result address. 

Link to module named, display 
address. 


Display all breakpoints. 

Set breakpoint at result address. 
Kill all breakpoints. 

Kill breakpoint at result address. 
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Error Codes 
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Utility Commands 


M expression! Display memory dump in tabular 
form. expression2 
C expressionl Clear and test memory 
expression2 
S expression! Search memory for pattern 
expression2 
$ text Call OS-9 Shell 


Q 


Quit (exit)/DEBUG 


DEBUG detects several types of errors and displays a corres- 
ponding error message and code number in decimal notation. 
The various codes and descriptions are listed below. Error codes 
other than those listed are standard OS-9 error codes returned by 
various system calls. 


0 


ILLEGAL CONSTANT: The expression included 
a constant that had an illegal character or that was 
greater than 65,535. 


DIVIDE BY ZERO: A division was attempted us- 
ing a divisor of zero. 


MULTIPLICATION OVERFLOW: The product of 
the multiplication was greater than 65,535. 


OPERAND MISSING: An operator was not fol- 
lowed by a legal operand. 


RIGHT PARENTHESIS MISSING: Parentheses 
were misnested. 


RIGHT BRACKET MISSING: Brackets were 
misnested. 


RIGHT ANGLE BRACKET MISSING: A byte- 
indirect was misnested. 


INCORRECT REGISTER: A misspelled, missing, 
or illegal register name followed the colon. 


G9O@GOOCOCOROOSOOSSOOSOSOCSeSCeOeeeeeeeeeeeee ie 


RBREERERERERERRERERERERERERERERRERERAR SE EL 


10 


EI 


12 


13 


BYTE OVERFLOW: An attempt was made to 
store a value greater than 255 in a byte-sized 
destination. 


COMMAND ERROR: A command was mis- 
spelled, missing, or illegal. 


NO CHANGE: The memory location did not match 
the value assigned to it. 


BREAKPOINT TABLE FULL: The maximum 
number of 12 breakpoints already exist. 


BREAKPOINT NOT FOUND: No breakpoint 
exists at the address given. 


ILLEGAL SWI: An SWI instruction was encoun- 
tered in the user program at an address other than a 
breakpoint. 
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TEXT EDITOR INDEX 


C 


Command Series Repetition 26 
Conditionals 26 
Commands 4 
Entering 4 
Parameters 6 
Numeric 6 
String 6 


D 


Deleting Lines 15 
Displaying Text 11 


E 


Edit Macros 30 
Headers 31 
Parameter Passing 31 
Edit Pointers 4 
Moving 12 
Editor Error Messages 66 


Inserting Lines 15 


M 
Manipulating Multiple Buffers 21 


S 


Searching 17 
Substituting 17 
Syntax Notation 7 


“ 


Text Buffers 3 
Text File Operations 23 
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ASSEMBLER INDEX 
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A 


Addressing Modes 83 
Accumulator Addressing 83 
Accumulator Offset Indexed 89 
Auto-Decrement Indexed 90 
Auto-Increment Indexed 90 
Constant Offset Indexed 87 
Direct Addressing 85 
Extended Addressing 84 
Extended Indirect Addressing 84 
Immediate Addressing 83 
Indexed Addressing 87 
Inherent Addressing 83 


Program Counter Relative Indexed 88 


Register Addressing 86 
Relative Addressing 84 
Assembler Directive Statements 97 

Assembler Input Files 73 


D 


Data Sections 115 
DEFS Files 105 


E 


Error Messages 121 
Evaluation of Expressions 79 
Expression Operands 79 


O 


Operating Modes 74 
Operators 80 


p 


Position Independent Mode 116 
Program Area 116 

Program Sections 115 
Programming Techniques 115 
Psuedo Instructions 91 


@9ee@eoeeeeeeeeeeedeeeeeeeeeeeeeeeeeee ed @ @ < 


0000060000000 OOOOOOOOOOOOOOOOCCOCCE®O 


S 

Source Statement Fields 77 
Comment 78 
Label 77 
Operand 78 


Operation 78 
Symbolic Names 81 
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INTERACTIVE DEBUGGER 
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Breakpoint Commands 152 


C 


Calculator Commands 147 
Calling DEBUG 141 
Change Commands 148 
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Debug, Calling 141 
Debug Commands 147 
Dot Commands 148 
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Expressions 143 
Constants 143 
Forming Expressions 145 
Indirect Addressing 146 
Operators 145 
Register Names 144 
Special Names 144 


M 
Memory Examine Commands 148 
Pp 


Patching OS-9 Component Modules 162 
Patching Programs 161 
Program Setup Commands 155 
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Register Change Commands 151 
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Run Commands 155 
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